Thursday, April 28, 2016

From reStructuredText to DITA... and back?

My life as technical writer started around 2003. Since then I've been using mainly a CMS, wiki, a very short period DocBook and the last couple of years reStructuredText (reST). Recently I've started working with DITA (Darwin Information Typing Architecture) to replace reST. At the company where I'm employed the main tool to edit DITA is oXygen, which is a nifty well-equipped editor, not to say the reference tool for DITA editing. Having used Vim for quite some years as editing tool for reST, oXygen is quite overwhelming when you start it for the first time. Of course I could reconfigure my Vim for DITA editing but that would take quite a lot of time, which I don't have. Still looking for a decent Vim setup though...

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...