The Crash Course to DocBook

1.2. Why DocBook?

The DocBook format was designed by OASIS consortium specifically for technical documentation. It provides a rich set of tags to describe the content of your document.

Here is a number of key points that help understand what DocBook is:

Docbook is a markup language

It is very similar to HTML in this respect. The tags give some structure to your document, and appear intermixed with the informational text.

This pecular point makes it a revolution with respect to documentation translation, because the DTP phase (making the text look nice) is done once for all indirectly by tagging the original text. The translators only have to translate "in between the tags" and by pressing a single keystroke the translated output is generated.

It is made for technical documentation

DocBook is perfectly suited for car engine parts documentation. However, it is strongly biased towards computer programs documentation.

It is maintained by an independant consortium

The OASIS consortium is in charge of maintaining and making this standard evolve through the DocBook Technical Committee. This is a guarantee of independance in front of proprietary software and standards.

Major actors of the industry like Boeing or IBM are members of OASIS. Refer to the updated members list for further information.

Technically, DocBook is a SGML or XML DTD

This means that one can take profit of the many SGML and XML aware tools. While DocBook as an XML implementation is quite recent, it has a long history as a SGML implementation.

DocBook is not a presentation language

DocBook carefully cares about not specifying how the final documentation looks like. This allows the writer to concentrate on the organization and meaning of the document he or she writes. All the presentation issues are devolved to style sheets.

This ensures all your documents have a consistent appearence, whoever should be the technical writer.

DocBook is customizable

It is quite easy to customize the DTD to meet one's need thanks to its modular organization. But one must be aware that this must be done with respect to SGML/XML conventions and that it might introduce incompatibilities.

If DocBook is used in conjunction with Norman Walsh's modular stylesheets, it is also possible to customize the way a DocBook file can be printed or put online too.

DocBook is comprehensive

The large number of tags defined in DocBook guarantees that it can accomodate a wide range of situations and of processing expectations.

This in turn makes it a bit difficult to learn, but one can manage writing documentation knowing only a limited set of tags and referring to the reference documentation when needed.

DocBook uses long and understable tags

Example of such tags are <itemizedlist> or <literallayout>. This makes a DocBook text much easier to read than an HTML source for example. As a drawback, it can also become a bit tedious to type those long tags, but specialized modes in usual editors (like Emacs' psgml mode) can help out of this. One can use authoring tools as well.

DocBook does not ensure ascending compatibility between major releases

While this might seem a drawback, in fact it is not, because it ensures a clean design even if wrong choices have been made previously by the DocBook Commitee at OASIS, and because documents written with different DTDs can coexist on a same computer system.

Some of those key points are discussed in more detail in the next sections.