Don’t use DITA if you don’t have to

I am currently for a large organisation that seems to embrace DITA for their documentation. In theory this is a nice thing. There is a wealth of tools to edit dita files and to transform them to all sorts of formats. The reference implementation is the DITA OPEN TOOLKIT. First of all I am not impressed with the documentation. There is no proper tutorial and no good overview. And these are people who are into writing documentation!

The second problem is the poor quality of the tooling. It a pile of ant build files, XSLTs and obscure jar files. This stuff is really brittle. Also it seems that people are not really concerned about having a decent continuous integration process. Documentation is rendered on some developer box, that has the “right” version of the toolkit installed. Clearly not everything that has the name Darwin on the box is good. The Practices of Proper Christian Programming have certainly not been followed. The whole thing is terribly brittle. Countless hours have been wasted, are being wasted and will be wasted. This is very unfortunate because documentation is often treated as a third class artefact that gets created as an afterthought using terribly blunt tools.

One decent resource is actually DITA for the Impatient. Generally I would advise to use a custom tool chain to build your documentation. Probably something involving a templating language. Transformations should be implemented in a real programming language. As a backend things like LaTeX come to mind. Also ant is actually a crappy tool even for compiling java code, so providing decent command line utilities is key for a toolkit that claims to be universal and extensible.

Verdict: Stay clear of DITA.