Writing Manuals

---

There once was a time when every software application came with complete written documentation—or at least, if there wasn’t such a golden age of documentation, many aging developers remember it that way. In recent years, the rise of online help in various formats has led to a definite decrease in the quantity (and some would say quality) of documentation. Some applications still include written manuals. Others include part of their documentation in writing but refer the user to help files for details. Still others include Adobe Acrobat (PDF) files that you can print yourself—or no written documentation at all.

Whether to include a written manual with your application needs to be a business decision as well as a technical one. The plain fact is that printing manuals is expensive, and in an age of cost-driven purchasing decisions, raising your price can be fatal to your sales. But if you do decide that a manual is warranted, here are some things to think about:

• Your help file can be a good starting point for your manual, but it likely will not supply the entire content for the manual. The written manual is more often used for reference than for task-based help, and so is a good spot to expand on technical details and background information.

• Consider starting the manual with overview and tutorial material that doesn’t really fit into a help file. Remember, users will have the help file for task-oriented help to use as an adjunct to any tutorial you present. This gives you the flexibility to introduce topics in the manual in a structured fashion, knowing users can go back to the help if they want to jump around.

• If your program is at all difficult to install, then detailed installation instructions belong in the printed manual (and in a readme file on the installation medium as well). Remember, users won’t be able to use your help file until after they’re installed the application, so installation instructions in the help file won’t do much good.

• Do your best to make the manual interesting to read. If it’s a hopelessly dull recitation of the application’s features, with nothing to teach users or motivate them to understand the underlying concepts, it will likely be just a waste of dead trees. You should think about what you want your manual to accomplish, and then try to accomplish those aims with a light, easy style.

Tip

One thing to consider when deciding whether to include a printed manual with your product: a lengthy manual can act as an unobtrusive antipiracy device. Although it’s possible for pirates to scan a manual back to a file, in practice most casual pirates won’t bother.

---