Anyway, while switching regularly between DITA and reST, and thus between oXygen and Vim, the DITA markup couldn't convince me as format. Was it due to oXygen as tool or was it really the markup, don't know, probably a mix. When I recently travelled to the US, I had a huge jetlag, so I got awake every day in the middle of the night. As my documentation in reST had to be transformed to DITA format, these nights provided me some extra hours to get the job done. During these nightly hours I got to know DITA and oXygen a lot better and I have to admit, I started to appreciate the markup and the tool.
At first there seemed to be too many restrictions in DITA but after taking the first hurdle of getting a bit more familiar with the editing tool, it all became more clear. Especially when you switch from an unstructured language, the DITA markup seems so restrictive, but in fact it isn't. On the contrary, it even helps me in writing documentation. While using the DITA markup more and more I get to appreciate some of the features like reusing content, the easy way of adding indexes and metadata, and so on. And after my 2-day training with Yves Barbion at Flow, formerly known as Teka Infopilots and Scripto, I even have some more sympathy for DITA.
So don't I have cons to DITA? Of course there are. The major con is the way of branding your documentation; this is cumbersome, especially if I compare it with reST.
Suppose you have an identical manual for company A and company B but both companies have their own product names and product versions. Since we don't want to copy the content from one company to another and then apply a find/replace, we'll use variables.
In reST, define I just have to store my variables in a Python dict in my project's configuration file, where the key of the dict is the company name and the value is the a list of values. In this example I would have a dict like this:
my_variables = {
company_A : ('company_A', 'A_product_name', 'A_product_version'),
company_B : ('company_B', 'B_product_name', 'B_product_version'),
}
In the same configuration file I have to define which variable name I have to use in my sources and then of course use the variable names in my sources. When building the output, I just have to select which company I want and build. In DITA this is far more complex as far as I know. Because the only way I found now is that you need a ditamap, a key definition file and a variables file per company, which means six files to maintain only for two companies. Still looking for a way to this in a conditional way, which would make it a lot easier.
Besides this major disadvantage, there's some other minor disadvantages, but if one would ask me now what I'd choose between the two of them?
Well, it all depends on the project. Even Word could do the trick...
