Product release preparations: Product documentation

Creating product documentation is necessary for preparing your product for release. These documents assist customers with using the product and troubleshooting potential problems. Documentation is important for every type of product, although the level of detail and types of documentation can vary.

Types of product documentation

• Single-file documentation (print or electronic): This document contains in one location all of the information required for the product. It also includes a table of contents and indexes.
• Searchable online help: The document presents information in web format. It enables users to view the table of contents, and search for items of interest.
• Context-sensitive help (software only): This document provides information to the user in snippets as required. Question marks within the software identify links to content on the topic.

How to create product documentation

Consider the following guidelines when creating product documentation.

1. Know your audience.

It is important to understand your user when creating documentation (much as you would when creating the product). You may choose to create different guides for different types of users. For example, an end-users’ guide would include everyday tasks, while an administrators’ guide would include configuration instructions or specialized one-time tasks.

2. Keep your documentation simple.

Documentation should be thorough, but it should not be so lengthy that it impedes reading. Only 20% of a product’s features are used most of the time, so consider this fact when creating documentation. Insert a simple note to draw attention to a specific aspect. Do not overstate or repeat obvious facts. For example, you only need to state once how to start the application. Avoid unnecessary or irrelevant information. Your goal is to fulfill your readers’ need for particular information, and not to expound on everything you know about the topic.

3. Use diagrams.

Annotate screenshots to help users recognize the purpose of the information. Describe workflows using pictures to ensure that users understand how different parts of the product interact with each other. Provide captions with each picture to explain what users are seeing.

4. Accept the truth: People do not read product documentation.

Users rarely read product documentation. They will refer to documentation when they cannot solve something on their own. Arrange content in “bite-sized” pieces; this enables users to search quickly, resolve their problem and continue working. Include extensive tables of contents and indexes to help users easily locate the information they want.

References

Software product documentation. (2006). Avangate. Retrieved August 26, 2010, from http://www.avangate.com/articles/Software-product-documentation_22.htm
Writing good software documentation. (2006). Avangate. Retrieved August 26, 2010, from http://www.avangate.com/articles/Writing-Good-Software-Documentation_35.htm