Section 8.1. Technical Documentation

8.1. 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 sessions, consultants, executive briefings, press briefings, and exhibition and conference work. It can even take the form of books such as this one, which you may be reading in hardcopy, from a browser, or perhaps from some PDA-like device of the future.

8.1.1. Is Documentation a Separate Product?

Some products are unusable without their documentation, in which case the documentation is obviously a core piece of the product. (Some products are pretty unusable even with great documentation, but that's a discussion for another time.) Most projects find that the overall documentation of a product makes a large difference to the success of the product. In fact, if none of the documentation for a product is important enough to affect the product's release date, is it even worth the effort to ship the documentation with the product?

However, once an organization and its documentation group grows, the documentation is often treated like a separate product, complete with its own product numbers and identifiers. This may just be the same phenomenon as when different parts of the software become separated as the project grows. For closed software, the existence of separate price lists apart from the main product price list is one indicator of separated groups within a company.

To answer the question in the title of this section: most products need their documentation, and therefore the documentation is part of the product. To put it another way, documentation isn't a separate product, even if the group that produces it is separate from the group that writes the source code for the rest of the product. The opposite of this idea resurfaces later in this chapter as one of the Bad Ideas (see Section 8.7.1).

8.1.2. Writing Documentation Is Like Writing Code

For whatever reasons, few technical writers are able (or choose) to write good source code. Likewise, few developers are able (or choose) to create good documentation. This situation has been known to lead to an unfortunate lack of interest within each group in the other's work. This is unfortunate because both groups are necessary for a product to succeed. The lack of interest is particularly ironic because the processes of writing code and writing documentation are more alike than not. Since both activities are similar, what is helpful in a developer's environment is also similar to what helps writers.

Table 8-1 shows how writing code and writing documentation relate to each other.

Table 8-1. Writing code versus documentation

Writing code	Writing documentation
Source code is written in an editor or IDE.	Text is written with an editor or word processor.
Compilers generate warnings and errors about incorrect source code.	Spelling and grammar checkers generate warnings and errors about incorrect text.
Machine-readable executables are generated from source code.	Human-readable formats are generated from other file formats.
Source code is ported to different platforms.	Different human-readable formats and languages are generated from the same raw text.
If you don't have a compiler for a platform, you can't port to that platform.	You may not be able to convert your document to a particular format.

Direct similarities between documentation and writing code include the following:

• Both have files that go through multiple versions, so both benefit from using an SCM tool.

• Both benefit from making changes in the source files, not in generated files.

• For both activities, the more steps there are between the source files and the final product, the harder it is to understand where an error was introduced.

• Debugging documents can be like debugging a product. Examples of questions asked during debugging are "Which source file lines make the product behave in this way?" and "What change in the documentation files made all these paragraphs narrower in the generated document?"

• Both benefit from usability testingfor example, whether a UI is easy to use and whether information can be readily retrieved from a document.

• Both products have errors, and their errors can usually be tracked using the same bug tracking tool. Documentation can be treated as just one more part of the product.

• Both need to track many different kinds of errors in their product. So both need tools to help analyze their text or source code in ways that change over time. This is work beyond the common spelling checks or compiler warnings; it can involve static analyzers (see Section 6.5.4) or tools that check cross-references.

• Both need to be packaged carefully for release as a product, and both benefit from automating the process of generating a release.

• Both groups often have a tendency to want to deviate from style guides, and they also avoid tools that weren't invented locally.