This is a single archived entry from Stefan Tilkov’s blog. For more up-to-date content, check out my author page at INNOQ, which has more information about me and also contains a list of published talks, podcasts, and articles. Or you can check out the full archive.

DITA Bashing

Stefan Tilkov,

Gernot Starke has some serious criticism of DITA … Docbook — which we have used for documenting our own product — in my experience, is different — while Gernot has a point with regards to change tracking and embedding of images, I still find the benefits (like being able to output different formats from the same source) outweigh the disadvantages.

On December 8, 2005 12:22 AM, Olli said:

I strongly agree to this point of view. In the automotive industry some companies defined the MSR standard, an XML-based format in order to exchange technical specifications.

Since it provides no way to exchange common engineering stuff like Simulink models, the funeral of this bullish is (hopefully) quite close. It is just a vehicle to pretend a “complete and accurate” spec.

On December 8, 2005 8:21 AM, Gernot Starke said:

yeah - different output formats might be fine - IF you really need them. In the cases I experienced, only printed paper docu was really required - and the slow-motion-docu process did imho NOT turn out valuable…

It is perfectly clear that to exchange structured info, things like DocBook or DITA are fine.

On December 8, 2005 1:41 PM, Gullydeckel said:

I like docbook. IMO, Gernot misses a couple of points:

  • use emacs. You won’t need a non-deterministic specialized tool
  • docbook (and probably dita) are for technical documentation, not for writing your proposal and co-editing it with an accountant. I agree that is next to impossible to make non-techies use it
  • OTOH, techies will like documenting stuff better (due to higher coolness factor)
  • DMS not necessary, just use your favorite version control system. this is the principal advantage, BTW. You will then have the desired re-use (at least for glossary, qanda, bibliography, …)
  • style sheets etc. are easy; just use your customers layout with your tool chain
  • it can itself be generated from other (XML) sources; concept is particularly powerful in an MDA environment