DocBook

By Andrew Clifford

Big documents like user manuals are really hard to write using Microsoft Word. DocBook is a well-established standard that makes writing big documents much easier.

I needed to write a handbook on system governance for our clients. It is a complicated document that we will need to maintain for many years as our consultancy work grows.

I have written documents like this using Microsoft Word, but I found a lot of things difficult:

• Using the output for more than just print. Word's HTML is not suitable for the web. If I want PDF output, I have to buy more tools.
• Splitting a long document into multiple files. This makes it easier to change the document and to create alternative versions. In the past I have had to create lots of little documents and put them together after they have been printed.
• Getting cross references, tables of contents and indexes to work reliably. These are OK on a single document, but too unwieldy on anything more complicated.
• Keeping the documents up to date with the latest version of Word. I have used five versions of Word in the past 15 years, each introducing new incompatibilities.

OpenOffice.org makes it easier to keep up with the latest versions and can produce PDF straight from the tool. But it can not easily address the other problems I found with managing long, complicated documents and producing different versions in multiple formats.

I searched for alternatives and found DocBook. DocBook is an open standard for documentation, originally developed over 15 years ago by the publishers O'Reilly and others. It is supported by many open source and commercial tools.

DocBook is designed for complicated documents like technical manuals. It lets you write your document as multiple files, and processes these into many different formats including PDF and HTML. It formats the document automatically based on its content. It manages tables of contents, cross references and indexes. It lets you tailor the formatting without altering the source.

DocBook takes a bit of getting used to. I had to manually mark up the documents, and it took me a while to configure the formatters to produce the output I wanted. Some of this might have been easier if I had been using established commercial tools rather than the latest open source products.

But the results are exactly what I wanted. I can produce good quality printed output, with comprehensive tables of contents, cross references and indexes. I can produce the document as PDF, or as multiple linked web pages. If I wanted to, I could create Windows Help files, or rich text format to use in Word.

The document is produced from many separate files, which I control using familiar source code management tools. I can reuse the document files in many ways, for example to create tailored documents for individual clients.

If you need to write and maintain complicated documentation, you will struggle with a word processor. I recommend DocBook as an effective and viable alternative.

Subscription