The real benefits of the new documentation toolchain are becoming more and more apparent.

As a simple example, a single text file defines the Product's four part version number. The build system processes this file to make sure the correct version number appears where it's needed: in the user interface, in the CD install script—and, of course, in the documentation.

Another example. If we get a support call which we think could have been avoided had the documentation been better, then we fix the documentation directly. Anyone with access to the revision control system and a text editor can make the fix. The full printed and online documentation will be regenerated when they next do a build, and will automatically be included in the next release.

And a final example. The Product I work on checks file-based digital video: it can spot unpleasant compression artifacts, unwanted black frames, audio glitches and so on. The range and depth of these checks is perhaps the area which changes most frequently: when we add support for a new video codec or container file format, for example. The architecture we have in place means that these low level enhancements disrupt the higher levels of the software only minimally: in fact, the user interface for this part of the Product is dynamically generated from a formal description of the supported checks. Adding a check at this level is a simple matter of extending this formal description. We also need to document the check: perhaps a reference to the codec specification and a precise definition of the metrics used. With an intelligent documentation toolchain the documentation can live alongside the formal description and build time checks confirm the help text links up properly.

From an engineering point of view, documentation is properly integrated into the Product. I finish with another quotation from Stayton:

Setting up a DocBook system will take some time and effort. But the payoff will be an efficient, flexible, and inexpensive publishing system that can grow with your needs.

Copyright © 2006 Thomas Guest