Single-source Documentation - Docbook Versus DITA
- By Teresa Mulvihill
- Published 02/28/2008
- Computers and Technology
- Unrated
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.
1. 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.
2. 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
3.Context
Docbook: book (section) oriented
DITA: topic oriented
4. Key Features
Docbook: large set of elements and attributes targeted for technical documentation
DITA: topic based, separation of content and context, specialization
5. Download and Installation
Docbook: bat,
bin, dtd, etc. files and eDE able to run with as is
DITA: bat, bin, dtd, etc. files, and transformation engine
6. Document File
Docbook: regular XML file called an include file with all files included in the document
DITA: ditamap file with all files and each file’s related links
7. Output
Docbook: PDF, HTML, HTMLHelp
DITA: unrestricted, but all need development
8. Community
Docbook: well supported by the XML community
DITA: small but strong, growing community
9. Complexity
Docbook: 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
10. Possible Needs
Docbook: Content Management System
DITA: 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 (see image at http://www.livetechdocs.com/blog/wp-content/uploads/2007/12/04_DBvDITAStructure.png).
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 (Flatiron 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.
1. Documentation volume
Docbook: small and medium
DITA: large
2. Documentation output
Docbook: PDF, HTML, HTMLHelp, others with development
DITA: all with development
3. Basic integration time frame (no conversion)
Docbook: one business day
DITA: one month plus
4. Budget
Docbook: small to medium
DITA: 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 (www.livetechdocs.com/blog), or send me an email teresa.mulvihill@livetechdocs.com.
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.
1. 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.
2. 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
3.Context
Docbook: book (section) oriented
DITA: topic oriented
4. Key Features
Docbook: large set of elements and attributes targeted for technical documentation
DITA: topic based, separation of content and context, specialization
5. Download and Installation
Docbook: bat,
DITA: bat, bin, dtd, etc. files, and transformation engine
6. Document File
Docbook: regular XML file called an include file with all files included in the document
DITA: ditamap file with all files and each file’s related links
7. Output
Docbook: PDF, HTML, HTMLHelp
DITA: unrestricted, but all need development
8. Community
Docbook: well supported by the XML community
DITA: small but strong, growing community
9. Complexity
Docbook: 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
10. Possible Needs
Docbook: Content Management System
DITA: 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 (see image at http://www.livetechdocs.com/blog/wp-content/uploads/2007/12/04_DBvDITAStructure.png).
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 (Flatiron 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.
1. Documentation volume
Docbook: small and medium
DITA: large
2. Documentation output
Docbook: PDF, HTML, HTMLHelp, others with development
DITA: all with development
3. Basic integration time frame (no conversion)
Docbook: one business day
DITA: one month plus
4. Budget
Docbook: small to medium
DITA: 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 (www.livetechdocs.com/blog), or send me an email teresa.mulvihill@livetechdocs.com.
Teresa Mulvihill
With over eleven years experience in technical communications, Teresa Mulvihill has a wide range of experience in documentation, including hardware, software, and network security. Her expertise lies in developing XML publishing solutions for companies of all sizes. Teresa Mulvihill also founded LiveTechDocs, an online collaboration service for documentation. Website: LiveTechDocs
View all articles by Teresa Mulvihill