Practical Development Environments

Chapter 8. Documentation Environments

This chapter discusses what documentation provides for a product and who the customer is for the different kinds of documentation. This chapter also shows that development environments for documentation teams are similar to the development environments used by developers writing source code.

Some of the most commonly used file formats and the related tools for creating documentation are examined, and there is a discussion of how the different parts of creating the final versions of documentation can be automated. This chapter doesn’t discuss writing style, different hyphenation schemes, or the flow of information in diagrams. I think that these topics are interesting, but they’re outside the scope of this book.

Technical Documentation

The aim of technical documentation is to make a product easier for customers to use and, by doing so, to reduce the effort (and cost) of supporting a product.

Documentation, at least for this book, is an umbrella-like term that covers:

• All paper-based products with words and images

• Online documents in formats suitable for viewing and printing

• Videos and other recordings

• Interactive training applications

• Online community newsgroups, mailing lists, and weblogs

While interactive “wizards” in applications such as spreadsheets do make the product easier to use, such wizards are usually considered part of the product, not part of the product’s documentation. Documentation can be for use by new or existing customers, for training ...