|Research, training, consultancy and software to reduce IT costs|
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:
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.Next: Inkscape and The Gimp
Minimal IT: research, training, consultancy and software to reduce IT costs.