How to format a user manual
The challenge with traditional user manuals is that they 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.
Want to read more? View my expanded blog post here, where I go more in depth on the topic.
Need help growing your business or nonprofit organization? Browse my website to learn about how I can help you with your particular needs.
Well said; well done.
2/28/2011 10:49:21 pm
Good Article and I totally agree...and would only add that should the documentation have to be updated...imagine all the extra work that would be needed to check all references and update the links...
Your comment will be posted after it is approved.
Leave a Reply.
Contact me at firstname.lastname@example.org.
Welcome to my blog. Please use the Category links below to find topics of interest to you, or just scroll through current postings.
Receive new postings via email: