8.1. Technical DocumentationThe 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:
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 CodeFor 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.
Direct similarities between documentation and writing code include the following:
|