In the end, though, all went better than we could have hoped.

I soon had the documentation build integrated with the Product build. Now the distributable ISO CD image had the right version of the User Manual automatically included.

I wrote a script to check the integration between the Product and the User Manual. This script double-checked that the various page/anchor targets which the Product used to launch the pop up Help window were valid. This script too became part of the build. It provided a rudimentary safety net as I rolled in more and more content.

Next, I cannibalised the good bits of the existing manual. We knew what problems we had seen in the field: some could be fixed using better examples in the Help text; I fixed these next.

Within a couple of days the new manual had all the good content from the old manual and none of the misleading or inaccurate content; it included some new sections and was fully linked to the Product. It was, though, very light on screen shots.

In an ideal world we could programatically:

Then this program too could become part of the build and, in theory, the screen shots would never fall out of step with the Product.

Already we had some tools in place to automate data loading and to exercise the user interface. We still have no solution for automatically capturing and cropping the images, so we rely on human intervention. So far, this hasn't been a huge issue.

I had a workaround for the verbosity issue. I used QuickBook, one of the Boost tools. QuickBook is a lightweight C++ program which generates DocBook (BoostBook, strictly speaking) XML from a WikiWiki style source document.

Using QuickBook, we can write our previous example as:

[section Hello World]

    Here is the canonical C++ example program.

      #include <iostream>

      int main() {
         std::cout << "Hello world!" << std::endl;
         return 0;
      }
      
[endsect]

QuickBook documents are easy to read and easy to write. QuickBook does fall a long way short of the full expressive richness of DocBook but if all you need are sections, cross-references, tables, lists, embedded images and so on, then it's ideal. This master version of this article is itself written in QuickBook.

You can even escape back to DocBook from QuickBook. So if you decide your manual needs, for example, a colophon, you can do it!

It wasn't going to be hard to beat Word Doctor on build times. Currently, it takes about a minute to generate the full user manual, in PDF and HTML format, from source. A simple dependency check means this build is only triggered when required. The real gain here is not so much that the build is quick, but that it is automatic: not a single button needs clicking.