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. Once I had this basic step working, 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 be based on the tools I had just demonstrated. I said I'd be happy set up the toolchain. 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.

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 for us. I didn't know if we could be productive using it. At least we understood the limitations of the current tools.

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.