DocBook & DITA

DocBook

As mentioned in the XML project overview, we'll be converting the Word version of the Graduate Student Manual to DocBook 5, then using XSL transformations to convert this XML files to PDF and XHTML formats.

We'll spend the first part of the semester wrapping our brains around generic XML and the concept of single-source authoring, so it will be a natural progression to turn our attention to learning a little bit about DocBook, which is by far the most widespread implementation of XML in the field of technical publishing.

DocBook is an XML authoring system with a very fairly large and specific set of tags within its schema. Though developed primarily for software documentation, it has been adopted by many other types of companies to structure their documentation.

For those who want to work ahead, try your hand at the XMLmind editor we'll be using and read through the DocBook 5 Manual. The benefit of using a widely implemented XML architecture like DocBook is that schemas and XSLT stylesheets have already been prepared by various people in the open-source community. As a result, editors like <oXygen/> and XMLMind are more likely to support such a standard, which we can use right out of the box. Below are some support links for learning more about DocBook; example files and other resources can be downloaded via this zipped file.

DocBook

• DocBook Definitive Guide 5.0 - online version of O'Reilly book. See especially Chapter 2 on creating documents.
• LiveDTD: DocBook 5.0 - shows all elements within the DocBook DTD.
• DocBook Quick Reference - provides a brief explanation for each tag within the DocBook universe.
• DocBook 4=>5 Transition - describes features new to the 5.0 standard.
• DocBook XSL - a really good summary of how to use the standard DocBook XSL to make transformation to XHTML and PDF.
• DocBook Tools - a general description of DocBook 5 tools from Open Solaris.
• DocBook Forum - from Nabble.com. Good, active community.

Simplified DocBook

• Simplified DocBook Intro - conceptual overview of the Simplified DocBook standard.
• Simplified DocBook Elements - a glossary of all Simplifed DocBook elements.

Darwin Information Typing Architecture (DITA)

In the past few years, DITA has begun to encroach on the near monopoly that DocBook has enjoyed in enterprise structured documentation. What makes DITA so special?

In a word, "topics."

Just as the Semantic Web project is attempting to categorize concepts across the Web, DITA allows users to categorize all topics within a documentation set according to three basic types of information: tasks, concepts, or references.

This may sound incredibly simplistic, but the DITA architecture allows authors to write in a much more modular form than ever before, with the ability to structure documents and customize topics in numerous ways.

How is all of this different from DocBook? To answer that, read Edd Dumbill's Intercom article Lovely DITA, DocBook Fades.

While we won't be using DITA very much this semester, we will be reading an article or two about it and at least looking at what a DITA document might look like if we were to design a topic-based documentation project. Luckily, our XMLmind editor supports DITA as well as DocBook, so we'll take at closer look at DITA during our final class of the semester.