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.