Single-source documentation - Docbook versus DITA
by - January 9th, 2008
When it comes to documentation projects, primarily technical, medical, and scientific, using XML is a no-brainer. The heavy thinking comes when deciding which flavor of XML to use: DocBook or DITA (Darwin Information Typing Architecture). I have been a steadfast supporter of DocBook for over six years. I’d tried my hand at DITA and gave it up as a fad; lots of bells and whistles, but too complicated to integrate. And couldn’t DocBook do everything DITA promised anyway?
So when Allette Systems contacted me to speak on XML standards in SydneyAustralia, I jumped at the chance to prove to the documentation world just how wonderful DocBook is and how DITA falls short. Fortunately, my in-depth research opened my eyes to the benefits and limitations of both.
In a nutshell, DocBook has the advantage of age; it’s stable, easy to setup, and created for technical documentation publications. While DITA has the advantage of youth; it’s innovative, complete with its own architecture, and created for documentation outside the book. DocBook was hatched in 1991 by HaL computer Systems and O’Reilly. In 1998, Oasis gave DocBook its own technical community. A year later, DITA began evolving from cross-department teams within IBM. Its Oasis technical community was established in 2004.
My research and experimentation with these two standards is summarized in the following table.
|
|
|
|
|
Definitions |
DocBook is a document type definition (DTD) for writing technical books and articles, with the structure that such forms imply. | DITA is both a DTD and a set of rules for writing online contextual documentation such as software help files. |
|
Concepts |
DocBook is hierarchical by nature, and must be developed to allow for single-sourced content DocBook has a fixed element and attribute set. | DITA separates content from context, allowing multiple architectures of information DITA is extensible, allowing the definition of information types |
|
Context |
Book (section) oriented | Topic oriented |
|
Key Features |
Large set of elements and attributes targeted for technical documentation | Topic based, separation of content and context, specialization |
|
Download and Installation |
bat, bin, dtd, etc. files and eDE able to run with as is | bat, bin, dtd, etc. files, and transformation engine |
|
Document File |
Regular XML file called an include file with all files included in the document | ditamap file with all files and each file’s related links |
|
Output |
PDF, HTML, HTMLHelp | Unrestricted, but all need development |
|
Community |
Well supported by the XML community | Small but strong, growing community |
|
Complexity |
With a little development, DocBook can do what DITA is attempting on a smaller scale | DITA is impressively engineered, but can be too industrial-strength |
|
Possible Needs |
Content Management System | Publishing plug-ins |
DocBook is well supported, easy to integrate, and tailored to technical documentation needs. DITA has a highly technical, innovative community, can (with development) publish to all online formats, and comes with its own architecture (content management).
So how do you decide? Well, the good news is DocBook and DITA are quite similar in basic elemental parts and XML tags. For example, DocBook is built on sections, which can be compared to DITA’s topics, as shown in the figure below provided by Flatirons Solutions.
Why is this good news? Because smaller companies, or those new to XML, you start with DocBook and graduate to DITA when and if needed.
Online communities (Oasis Open Document) and companies (Flatirons Solutions) are already attempting to facilitate compatibility between these two standards.
The table below may help you decided which standard is right for you and your company today.
|
|
|
|
Documentation volume | Small and medium | Large | Documentation output | PDF, HTML, HTMLHelp, others with development | All with development |
| Basic integration time frame (no conversion) | One business day | One month plus |
| Budget | Small to medium | Medium to large |
I am always interested in your comments and experiences, especially if they differ from mine. Please feel encouraged to comment on this blog, or send me an email teresa.mulvihill@livetechdocs.com.
Teresa Mulvihill
February 25th, 2008 at 9:24 pm
[…] LiveTechDocs Blog » Blog Archive » Single-source documentation - Docbook versus DITA “Why is this good news? Because smaller companies, or those new to XML, you start with DocBook and graduate to DITA when and if needed.” (tags: docbook dita comparison) […]
March 28th, 2008 at 7:20 am
[…] Docbook versus DITA Not the first comparison I’ve seen but an excellent summary comparison of DocBook versus DITA. Whilst it was written by someone who admits that they were looking to portray a favourable outcome for DocBook, it’s an well-balanced set of information and will be useful to many. […]
March 29th, 2008 at 7:02 am
[…] curious might want to check out this comparison of DocBook and […]
March 31st, 2008 at 3:26 pm
[…] on 1 April: Check out this excellent comparison of DocBook and DITA by Teresa […]