“Read the friendly manual!” (Or something like that.) We don’t hear that saying as often as we used to, because so much software doesn’t come with friendly manuals. It’s a shame. Help menus and FAQs are useful, but they aren’t a substitute for great software user guides that explain the application systematically.
Good software user guides serve two purposes: let the user learn the product, and provide a reference for more experienced users. Sometimes they’re two separate documents, especially if the software is really complex. Usually one is enough.
Most software user guides today are PDF files. They save the cost of a physical book, and the ability to search them makes them more useful as reference guides. The guide has to contain actual text and not be a scan of printed pages. It should take advantage of PDF’s outlining capability, with chapters and at least one level of subheads.
Look for a “tagged PDF” option when creating the file. Tagged PDF has accessibility features and is more user-friendly.
Chapters
The first thing to think about is the chapter organization. On a high level, it should look like this:
- Introduction
- Installation and configuration
- Basic usage
- Special features
- Troubleshooting
- Glossary
- Function reference
The introduction gives get their first impression of the manual here, so it’s worth extra effort to make it brief but welcoming. The next few chapters should lead the user through installing the software, doing any necessary setup, and launching it for the first time.
Every explanation needs to be clear and step by step. When in doubt, err on the side of explaining too much. If the software uses any special terminology, define it before using it, and define it again in an appendix. What’s clear to you isn’t always clear to someone using the software for the first time.
One or more chapters should follow on performing normal operations. If it’s a document-oriented application, they should explain how to create a simple document, save it, and open it again. For other kinds of applications, they should explain some of the most common tasks users will do.
Illustrations help. Users learn by seeing, not just by reading words.
The next chapters should cover the remaining functionality, including functions not yet touched and any information not yet covered about the basic functions. It’s very unlikely readers will go through these chapters in sequence. Rather, they’ll find the parts they need and read them for what they’re trying to do. Each chapter should cover a well-defined topic and be self-contained. It should cover each action in detail and include all options.
Appendices
Appendices are strictly reference material. People will go to them only when they’re having a problem. The guiding principle is to list specific topics or issues so they’re easy to look up.
A troubleshooting guide is often useful. It should briefly describe specific problems that might occur, followed by what to do about them. It should repeat the support contact information.
A glossary may be a good idea if the software has a lot of unusual terms.
A function reference can list all menus, preferences, options, and so on, systematically but briefly. The purpose isn’t to explain them but to enumerate them. It might include cross-references to the chapter that explains them.
Is an index necessary in a searchable PDF? Opinions vary on this. A purely computer-generated index doesn’t do much that a search can’t do; if there’s an index, a human should at least review it.
What makes software user guides stand out?
Software user guides come at all levels of quality. A good user guide, more than anything else, needs to be well written. A document with overly complicated sentences, poor grammar, or illogical flow is a 
poor document, whether it’s a novel or a technical manual. A good tech writer needs to be a good writer.
Leave out the suspense, plot twists, and shocking revelations, though. After good writing, what a technical document needs most of all is clarity and completeness. It should make even difficult topics look easy. The user guide shouldn’t make the user do extra work to figure anything out, but should make it as simple as possible to use the software.
Unstoppable Software creates software that works, on time and in budget. If you’ve got a project in mind, please contact us.
