Stop the Presses

In despair over documentation

Last weekend, I installed a Web cam and was aghast at the poor quality of the documentation that the vendor provided. I might have assumed that the vendor felt justified in cutting corners on an instruction guide for a $69 product if my work in the Windows 2000 Magazine Lab hadn't taught me otherwise. The products we review often cost thousands of dollars, but I've found little or no correlation between a product's cost and the quality of the information the manual provides.

As you can imagine, not every product we review works perfectly the first time we install it. Sometimes a problem is our fault: We've overlooked a step or haven't properly configured our network. But more often than not, the problem is the result of missing or incorrect information in the vendor's documentation. In the Lab, we consider those problems part of the review process, but when you have such problems, a lot more is at stake.

In the rush to quickly bring products to market, some vendors seem to print product manuals before the technical writers have received final details from the hardware or software developers. (One of my pet documentation peeves is screen illustrations that don't match the actual product screens. Obviously, the technical writers were working with an earlier product version.) The problem only gets worse as product cycles shorten. And many vendors want to avoid the expense of reprinting manuals, even when the current manuals are outdated or contain mistakes.

Configuring the product to suit your application is another challenge. Some manuals contain an overview of the product's components. In some cases, these overviews even point you to appropriate sections of the manual for typical usage scenarios. But other vendors provide no paths through the product's documentation. This practice forces you to search through the manual—or worse yet, read all the provided documentation—before you can configure the product to meet your needs.

In the Lab, we sometimes don't find a manual's faults until we've worked with the product for a while. When we finally run into a problem and turn to the product documentation for a solution—and if we can find the information we need—we often can't understand the documentation because it is so poorly written. Haven't we all seen an unfathomable error message and found that the product's documentation contains almost no information about the message's cause or possible solution?

We'll never get perfect manuals, but how much of an investment of time, effort, or money is necessary to produce acceptable manuals? Are we asking too much to have a technical support person test a product's installation and setup documentation to spot problems before customers do? If errors slip through the cracks, why can't vendors post amended .pdf files on a Web site and reference that URL inside the manual's front cover? Creating outstanding software is tough, but writing a decent manual shouldn't be.

Although poor documentation does increase the workload for vendors' technical support staff, many vendors' senior managers apparently don't recognize the decrease in customer satisfaction that such documentation also causes. The next time poor documentation inconveniences you, take a moment to email a complaint to the vendor's product manager and company president. We promise to do our part and notify you of documentation problems when we review products, but customer feedback is more likely to get the vendors' attention.

Hide comments


  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.