The documentation challenge

Documentation comes in many forms, such as release notes, installation guides, FAQs, command and GUI reference manuals, user guides, tutorials, and training guides.

This article will cover the importance of good product documentation, what some of the hurdles are in creating it, and provide a few suggestions for producing quality documentation.

Importance of good documentation
The reason that the customer bought your product was to make their life easier. If, while using the documentation, it is difficult to figure out how the product works or to get questions answered, typically one or more of the following will happen: He or she will quit using it, tell others not to buy it, or contact your customer support.

None are good options since they will either reduce sales or increase costs because of the need for extra support, not to mention tarnishing a company's image. In the long term, fixing the problem with support is most expensive, compared to fixing it with documentation (less expensive), or with software quality (least expensive).

Documentation challenges
There are several challenges in creating effective documentation. Let's look at few key issues.

1. Many companies are trying to cut costs, especially in a bad economy, and often documentation is not adequately staffed or cut.
Recently, I saw a mid-size company lay off most of its technical writers to cut costs. They were mostly senior writers — as editors and junior writers were laid off in previous years —, had extensive knowledge in using the product, were efficient writers, were experts with documentation tools. Most had technical backgrounds. Developers are now responsible for the core documentation, which they pass on to someone else, whose main responsibility is putting the information in the proper format.

This resulted in adding an additional task to an overworked developer who does not want to do it, does not have the writing skills, and is paid at a higher salary. The negative impact to the documentation and the employee is significant. This is not just because of unhappy customers, but also because critical engineering time is being used to write documents.

Let's take another recent example. A small startup understands the need to have a technical writer produce quality documentation. The result was that it was able to provide up-to-date Command Reference, Graphical User Interface Reference, and User Guide manuals to include in its product release. This included table of contents, indexes, and many links within and between the manuals to make it easier for the customer to find information quickly. The focus was on accuracy, simplicity, consistency, and maintainability. Further, it will significantly reduce support time and provide a good foundation as additional features and documents are included in the future.

Creating documentation not only helps the end user, but also the provider. If the writer has a technical background and runs the product to get an understanding of what needs to be written, he or she can provide input to the product — inconsistencies or gaps, for example. He or she can file bug reports, and indirectly, are testing the product. This also means the writer can accomplish more things on their own, leaving fewer questions for the engineers.

The product may be intuitive and engineers may be smart and able to figure out much of the product, but they will still need documentation. If it is difficult to document a product or a feature, there probably is a problem with it, and it needs to be improved. Getting input and feedback on the documentation from customers, R&D, support, marketing, and QA helps create accurate documents that are useful for the customer.

A company's image is an often overlooked, but important benefit of quality documentation. Done well, documentation can create the perception that the company is well run and well managed, and makes customer support and service a priority.