06 December 2005

How to slow down your project (DITA bashing)

just in case you need to stall your project, slow down progress and eliminate most of the unwanted agility of your folks: Try out markup documentation. Instead of writing with a word processor or a wiki, make your guys use some strange markup language. DITA (Darwin Information Technology Architecture) is a great example. I stumbled over it in a recent project. My personal estimate is that one needs at least three (3!) times as long to document something than with one of those old-fashioned but simple tools like wiki or a word processor (A few of my comments hold for docbook too...)

Why that? Isn't the whole world calling for more structure, for markup languages?

Might be - but markup documentation suffers from several serious drawbacks:
  • You need pretty elaborate tool chains to efficiently produce such documentation. To really work with DITA for example, some ant scripts and a little xslt may seem sufficient. Be assured - in reality it is not. Experience taught me you need at least a DITA-aware XML-editor and some fancy post-processor (like FrameMaker).
  • You need a build cycle to compile your documenation sources into something visible. That's why smart people invented WYSIWYG editors some years ago - with tremendous success. And now DITA forces me to refrain from these productivity gains?! Agile development is about fast feedback, I heard :-)
  • You need some type of content management system to enable re-use of documentation chunks. In one of my projects DITA was introduced with the promise of single-source documentation. In reality it turned out that many chapters were written redundantly - due to a lack of content management. If you control vast sources of money, this one poses no problem for you.
  • You need to educate your authors. Sounds easy, does it? Please come back from fairy tail country: IT IS REALLY HARD to educate programmers to use anything which slows them down. About hundred different tags, no industry-wide accepted standard on when-to-use-what-tag, do we really need that complexity again?
  • Forget about copy and past some diagrams into your word-processor: Such quick (and sometimes really productive) actions are impossible in DITA.
  • You are working with plaintext format - no multi-user capabilities like "comments" or "change history".
My suggestion: Unless you are producing product documentation for a mass-market, stick to simpler tools. DITA documentation is NOT simple, it is expensive and slow. If you have the money and the time, DITA might be the right choice for you. I heard of books which were produced with docbook - but not many! For good reason - at least a few authors are smart and aware of their limited lifetime.