Regaining Control

My frustration with the existing documentation tools set me thinking about alternatives. I looked first to the open source world, where there's no shortage of excellent documentation and where the authors are happy to show how they generated it.

I experimented by downloading and attempting to build some open source documentation. This was a part time activity, squeezed into moments when I was waiting for builds to complete or files to check out. If the documentation didn't build or required lots of configuration to get it to build, I moved on. I was looking for something as simple as:

> cd docs ; make 

To my surprise and disappointment it took several attempts to find something which worked out of the box. Perhaps I was unlucky. No doubt in many cases it was user error on my part and no doubt I could have sought advice from email lists; nonetheless, I kept moving on until I found something which worked first time (my thanks to the Hibernate documentation team). Then I continued to experiment: could I change fonts, include images, replicate the house style? How easy were the tools to use with our own content?

After a Friday afternoon's experimentation I had something worth showing to the engineering manager: an end-to-end solution which, from a DocBook XML master, generated a skeleton PDF and HTML user manual in something approaching the house style.

I suggested to the engineering manager that we should switch the usermanual to use the tools I had just demonstrated. I said I'd be happy to do the work. He agreed with me that technically, this seemed the way forwards. However, it wasn't easy for him to give me the go ahead for the reasons already discussed. Also, it was a hard sell for him to make to the rest of the company: on the one hand, writing end user documentation simply wasn't what the engineers were supposed to be doing; and on the other, it was hard enough persuading the technical author to use the revision control system, let alone edit raw XML.

I confess I had my own doubts too. All I knew at this stage was that DocBook could do the job and that I would happily tinker with it to get it working. I didn't know if I could be productive using it. I don't relish editing XML either.

We both recognised that the single most important thing was content. Full and accurate documentation supplied as a plain README would be of more practical use to our customers than something beautifully formatted and structured but misleadingly inaccurate.

In the end we deferred making a final decision on what to do with the manual. The results of my experiment did seem worth recording, so I spent a day or so tidying up and checking in the code so we could return to it, if required.

Copyright © 2006 Thomas Guest