Section 8.6. Automated Production of Documentation


8.6. Automated Production of Documentation

Automation is just as useful when creating documentation as it is when writing source code. Every manual step of the process is vulnerable to human error. So if there are fewer manual steps, then the process becomes much more reliableand probably a little faster too.

One major benefit of regularly producing the final format of the files for the documentation is that it reduces the pressure on the writers as the release date for a product approaches. Each time the documentation is produced is a test of the production process, so there should be fewer nasty surprises when the release is due.

Another benefit is that intermediate versions of the documentation can be distributed more easily for reviews and beta releases. Just as with source code, regularly available proofs of the documentation help you catch formatting errors when they creep in, not weeks later when it's much harder to work out which particular change to the source files resulted in the changes in the documentation.

Some documentation requires so many manual modifications to an intermediate file format during production that there can only ever be one conversion from the input file format. A good example of this is creating a book from Word files, using FrameMaker as an intermediate file format. There is no easy way to record all the hyphenations, soft linebreaks, text-flow changes, and moving of figures in the original Word source files. I think that this effort is one of the great shortcomings of documentation environments as they are nowno one would imagine modifying generated assembly code by hand.


Even if they can do it more often, why is it that many projects generate their documentation only once or twice before creating a release? There are at least three reasons:

  • Generation of the documentation requires some specific tools that are not available on every machine, and these tools are not cheap.

  • Generation takes a long time, with lots of manual intervention to answer questions, enter values, and so on.

  • The final formats of the documentation are so close to the format that the writers use that they see no need to view the documentation in its final formats.

Some responses to each of these problems are:

  • Putting copies of the tools on more than one machine is an insurance against the possibility of that one vital machine failing just before the release is due. This insurance will cost something, but what's the cost of not shipping on time? How long will it take you to reinstall and reconfigure the required tools on a new machine?

  • If the tools really must be used on just one machine, then there are a number of ways of running a tool remotely. Source files can be made available using shared filesystems or can even be copied from one machine to another. On Unix machines, rsh and ssh can be used to run processes remotely, and GUI screens can be made to appear locally if necessary. For Windows 2000 and later, there is the Remote Desktop tool, which makes it seem that you are directly logged in to the remote machine. There is a similar product named VNC (http://www.realvnc.com) for a larger number of platforms. Of course, with a single machine there is also the issue of how to avoid problems when multiple people want to use the machine at the same time. A simple lock file that is generated as part of using the tools can be used to notify other people that someone else is already using the tools.

  • Every manual intervention will be done incorrectly by someone one day, which will make the whole thing take even longer when you have to start all over again.

  • The number of interventions can be reduced in a number of ways. Some tools will let you use a text file to provide canned responses to their questions. Other tools will let you pass in values to a command-line version of the tool. Open source tools can have the local defaults hardcoded in their source code. In the worst case, UI test tools can be used to enter the required values at the appropriate times.

  • What the writers see is close, but not exactly the same. Every difference between what writers see and what customers receive is a potential bug in the documentation. The analogous situation with source code is when developers never really use the product as it is shipped to customers, which is a surefire way to introduce bugs to a product.



Practical Development Environments
Practical Development Environments
ISBN: 0596007965
EAN: 2147483647
Year: 2004
Pages: 150

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net