Recently I spent some time working on a user manual.

The existing version of this manual was based on a Microsoft Word master document. From this master the various required output formats were generated in a semi-automated fashion.

I'm guessing anyone who's used a computer will have come across Microsoft Word: it's a popular tool which is easy to get started with and which, by virtue of its WYSIWYG interface, allows even a novice to produce stylish output. It does have its drawbacks though, especially for technical documentation, and these drawbacks were only amplified by the other tools involved in producing the final deliverables.

We'll look more closely at these drawbacks later. I summarise them here by saying the proprietrary tools and file formats led to a loss of control. The final outputs were not so much WYSIWYG as WYGIWYG—What You Get is What You're Given.

Producing high quality technical documentation is a difficult problem but it's also a problem which has been solved many times over. Plenty of open source projects provide model solutions. My increasing frustration with the Microsoft Word based documentation toolchain led me to explore one of these alternatives.

This article records the outcome of my exploration. It tells how, in the end, we did regain control over the manual, but at a price.

The requirements for the manual were clear enough. It had to look good. It had to fit the corporate style—dictating, in this case, font families, colour schemes, logos and various other presentational aspects. There would be pictures. There would be screen shots. There would be cross references. Naturally, the contents should provide clear and complete details on how to use the Product.

We needed just two output formats:

Of course, these two versions of the document would have to agree with each other. And the Product itself, a server-based piece of software with a web browser interface, should integrate with the online documentation in a context-sensitive manner: clicking the Help icon next to an item in the UI should pop up the manual opened at the correct location.

Finally, there was the slightly strange requirement that the documentation should be substantial [footnote This, to me, is a suspect requirement, or at least one we should keep in check, otherwise we run the risk of producing documentation whose sections are cut-and-paste adaptations of similar sections.]. Somehow, it seemed unreasonable to ask customers to hand over lots of money for nothing more than CD's worth of software; bundling in a weighty manual made the final deliverables more tangible.