Documentation isn’t what it used to be

Maybe it’s just nostalgia, but I recall a time when vendors made sure you got good quality, printed documentation with the hardware and software you purchased. Novell used to provide a ton of books with NetWare. When Borland International released its $100 TurboC product 17 years ago, the company wisely expended a good deal of effort to ship excellent documentation with the product. And the Netscape Enterprise Server documentation was – and continues to be – breathtaking in its clarity and usefulness.

Unfortunately, the number of vendors that supply clear, easy-to-follow hard-copy explanations of how to use their products is declining.

Good documentation isn’t everything, of course. You’ve likely noticed most Network World reviews’ scorecards appropriately give documentation a lower weight than ease of use, accuracy, reporting or performance. Nonetheless, good documentation is important not only because it explains how to use the product, but also because it serves as the first line of defense when a company experiences IT employee turnover and new folks have to fill old shoes.

Good documentation typically consists of a clearly written, comprehensive and descriptive user guide along with a technical reference manual. A quick-start guide is icing on the cake. Context-sensitive links are helpful for the online version of the documentation. Good English is important, as is a thorough index. The documentation should identify a product’s components, explain its benefits, show how to use the product and contain practical examples and illustrations. A hard-copy version of the documentation should be available for customers who want it.

Our network management systems review points to the manuals that Lucent provides with VitalSuite to be a shining example of the kind of useful, helpful and informative documentation that other vendors should strive for. In contrast, Fluke Networks’ user guide for its OptiView handheld network testing tool discusses how to recharge the battery and use the touch-screen based version of Windows, but it stops far short of describing how to use the OptiView software. It doesn’t even identify the reports OptiView can generate. SilverBack Technologies’ InfoCare documentation is fairly clear but only available online. Moreover, the InfoCare manuals are PDF files, which makes them impervious to context-sensitive use.

The reasons for poor or nonexistent documentation are many. A vendor might say it can sell at a lower price because it hasn’t spent money creating good documentation. Another vendor might tell you not to worry about the lack of documentation because it’ll gladly send system engineers to your site to train your people. Yet another vendor might claim that its user interface is so intuitive you won’t need documentation. All too often, a vendor’s engineers focus only on the hardware or software and think they’ve finished making the product when they’ve completed testing it.

These excuses are unacceptable, and I don’t want to hear them. I simply want to clearly understand how to use a product.