Latest posts by techwriter (see all)
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
- An Amazing and FREE Source of Magazines and Periodicals — ISSUU - November 25, 2016
The traditional form of help documentation is a hard copy manual that is printed out, nicely bound, and functional. It serves as a reference manual – skim the TOC or index, find the page, and follow the directions step by step. The challenge with these types of documents is that user manuals can often become jumbled and hard to understand. And in an effort to fix this issue, writers can try to employ what I call “look over here” techniques to minimize the wordiness and simplify the content.
I have found this approach to be extremely ineffective most of the time. Why? Because user manuals are not meant to be flipped through 10 times for one task. That is what online help is for.
So how can we create a good user manual?
Well, we do so by dividing the content up and presenting it in a self-contained manner. In this way, ALL of the information necessary to perform that task is present in that section of content. Take this basic scenario of a sample page from a user manual, and see if you can tell what’s wrong with it:
Logging into the application
1. Open the Start Menu. If you do not know how to access the Start Menu, see page 5.
2. Locate Application A, and double click to open it. For more information about how to do this, see page 2. If you do not see the program listed, go to page 6 for troubleshooting.
3. On the login screen, enter your user name. For more information about where to get your user name, see page 3.
4. Enter your password. If you have forgotten your password or are not sure what your password is, see page 4.
5. Click OK to log in.
Does it look concise and pretty? Yes. Does it appear easy to scan? Sure. But is it effective? No.
In the scenario above, we have turned five simple steps into an extremely complex, page-flipping process whereby the user has to go from page to page in order to perform a simple task. The workflow looks something like this: page 1, page 5, page 1, page 2 or page 6, page 1, page 3, page 1, page 4, page 1.
Why put the user through this? And imagine if the pages weren’t close together or there were 20 steps in the process? Let’s say the manual was 200 pages long, and the user had to flip from page 25, to page 72, to page 4, to page 169, etc…
The best way to format a user manual is to create self-contained modules that have all of the necessary information within the module. Page flipping should be minimized. However you must be careful to format the text so that it still maintains its readability. How do we do this? By using bullets and notes.
My rule of thumb is: have your main action in the step, and any supplementary instructions in bullets or a note. That way, if the user doesn’t need the extra help, he/she can move forward quickly and not be encumbered by excess information. Visit the Technical Writing section of the blog on my website for an expanded version of this article, plus a correctly formatted version of the example user manual page above.
Need additional tips and suggestions, or want help creating communications for your business? Visit my website at http://www.writerliz.com. I am a professional writer with nearly six years of corporate experience. I have a B.A. in English and can provide free writing tips to aspiring writers, or paid professional writing services to businesses and corporations.