Single-Source Documentation: Docbook versus DITA

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?

Mulvihill, Teresa. LiveTechDocs (2008). Articles>Documentation>Single Sourcing>XML

Single-Source from the Reader's Point of View

Documentation written for single-sourcing (topic based, like that found in DITA) has great potential for efficiency. Writing once and publishing in many publications (Developer Guides, User Guides, etc.) and many formats (pdf, html, HTMLHelp, etc.) turns into cost and time savings. However, these efficiencies can cause inefficiencies for the users. Many online help users complain they cannot find the information they need while using the search function. Readers are more likely to comprehend texts with a classical book architecture, an architecture which is often sacrificed in single sourced documents and online Help files. When texts are cohesive, readers are more likely to consider information to be clear, well organized and easy to follow. For comprehensibility, it is essential to have a manual review, even when composing is partially automated.

Mulvihill, Teresa. LiveTechDocs (2008). Articles>Content Management>Single Sourcing>Audience Analysis

XML Editors for Technical Documentation

Looking through my Programs folder, I see many programs I use to work with XML documentation. Which one is my favorite? Well, that depends on the size of my project, the size of my budget, and the file I am working on.

Mulvihill, Teresa. LiveTechDocs (2008). Articles>Documentation>Software>XML