BY EVAN KOBLENTZ
Technology Editor, TMC Labs™

Vendors: RTFM

Although I don't have a knack for it, working at TMC Labs forces me to be a multitasker. Usually, this means handling three reviews, a handful of vendor meetings, several miscellaneous tasks, and hundreds of electronic messages in a single week. All of this means that we're only as efficient as our weakest link, which too often shows its face in the form of bad product documentation. Ergo the theme of this week's column.

This week, for example, one product review I'm focusing on has a feature requiring the management of organizational forms in Microsoft Outlook. I can't say which product it is because the review hasn't been published yet. But anyway, the point is that organizing these forms from an enterprise product in conjunction with Microsoft Exchange is a rather complicated task, yet the instruction manual devoted a measly one-half page to the process. You could argue that installers should already be Exchange-fluent before attempting the job, but when I called the vendor's technical support team, it took one of their own managers took several tries and several hours to pinpoint the problem: it was finally solved by a brainstorm of mine, not theirs.

There's more. Another enterprise product I recently tested ( ironically, it's a product that's partially used for evaluating other products) included some printed documents, but no online documentation whatsoever. A vendor representative initially told me that in their opinion, their customers are smart enough to figure out how to use the product on their own. She later admitted that this was a pretty lame response.

Some products we see in the lab are better, but still not good. Most of them do have online help, but it's often not content-sensitive. Many times online help is all there is; with companies insisting that the cost of actually providing a printed copy of their 200-page Adobe Acrobat files isn't justified. Other companies include all forms of help -- printed, online, and Web-based -- but then they don't bother to proofread them. Some are proofread just fine, but then the documents are translated into English, which makes for some odd mistakes. Then there is something I call "unhelp": help documents that simply aren't helpful. For example, when you click a help button for an "Edit" command and the help says "Clicking this button edits the command." Gee, thanks, Mr. Technical Writer! Now I know how to do it!

To be fair, I've also seen some manuals that blew me away. My favorite example is SpeechWorks. Whoever writes the manuals for this company deserves their "Employee of the Year" award. SpeechWorks' documentation includes all of the essentials: printed manuals, online help, and a Web site with white papers that are actually informative. Then, they go a step further. The documents don't just discuss how to use their speech recognition software; they discuss how speech recognition software should be used, from planning to implementation. They don't just tell you how to do specific tasks, they give you real-world scenarios and examples. They include glossaries, integration appendices, lists of other speech recognition resources, and even a detailed academic lesson in how speech recognition works, down to phonemes and core algorithms. Everything is proofread flawlessly, and the printed manuals even have a nice, glossy cover. Now that's what I call documentation.

If you've read this far, you hopefully understand why this matters to you as a member of the SOHO CTI community. It's simple: your customers are people who, unlike the customers of the vendors I mentioned above, are not necessarily technical. Therefore, you need to be even more careful when you write documentation. You need to take very complicated technical material and explain it in a way that is appropriate for several levels of readers. This doesn't mean your manuals should simply be long -- some products that we've reviewed had documentation that was so verbose we evaluated it in pounds instead of pages. Obviously, this isn't a good thing: conciseness and comprehensiveness are equally important.

What's also important are illustrations, tables, screen captures, glossaries, indexes, and updated release notes. Do spend a few dollars on color printing and good paper stock -- don't send your customers stuff that's been photocopied and stapled. Do hire (or outsource) an experienced technical writer -- don't stick the job to an overworked engineer or marketing manager. Do respect your customer's intelligence -- but don't assume they are experts just because you are.

In the documentation section of product reviews, we usually say what's wrong, but we don't get to say what's right as often as we'd like to. Although the things listed here apply to any kind of computer telephony solution (or to any product/service at all, really), they hold especially true for SOHO-oriented products, because unlike many enterprise products, the SOHO audience is usually at a very different technical level than developers. Don't just follow the lessons presented here -- be creative! If your product has a TUI, then why not offer spoken help? Or videotaped help? Or Web-based training classes?

A final thought: if you've gone this far but still don't know what "RTFM" stands for, then do yourself a favor: Go back to the first paragraph, and read this -- er, FINE -- manual, again.

Evan Koblentz welcomes your comments at ekoblentz@tmcnet.com.