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 problem with a user manual format, in my opinion, is that it is very linear.
The challenge with these types of documents? 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 set up to be flipped through 10 times for one task. That is what online help is for (see an upcoming blog post for more information about that format).
As a writer trying to create a (good) user manual, it is better to divide your content up and present it in a self-contained manner. In this way, ALL of the information necessary to perform that task would be present in that section of content.
Example: Bad formatting
Take this basic scenario of sample pages from a user manual, and see what’s wrong with it:
Page 1
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. Let's take a look at the other pages the user has to visit in order to complete those concise steps on page one.
Page 2
Locating the application
Open the Start Menu and select the application from the list. If you do not see the program listed, go to page 6 for troubleshooting. If you do not know how to access the Start Menu, see page 5.
Page 3
Getting your user name
Your user name is sent to you by your administrator. If you have not received your user name, contact your administrator for assistance.
Page 4
Your user password
Your user password is given to you by your administrator, and you can change it through the Preferences page. Refer to your administrator email for the password, or contact your administrator for more assistance.
Page 5
Accessing the Start Menu
The Start Menu is located at the bottom left corner of the screen in your Windows application. Click it to access the Start Menu.
Page 6
Cannot locate the application
If you have installed the application but do not see it in the Start Menu, contact Customer Support for assistance.
Big problems
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...
Example: Good formatting
Let’s create user manual text that is effective. Here is a better version of the above information:
Page 1
Logging into the application
1. Open the Start Menu, which is located at the bottom left corner of the screen in your Windows application.
2. Locate Application A, and double click to open it.
Note: If you have installed the application but do not see it in the Start Menu, contact Customer Support for assistance.
3. On the login screen, enter your user name.
Note: Your user name is sent to you by your administrator. If you have not received your user name, contact your administrator for assistance.
4. Enter your password.
Note: Your user password is given to you by your administrator, and you can change it through the Preferences page. If you have forgotten your password or aren’t sure what your password is, refer to your administrator email for the password, or contact your administrator for more assistance
5. Click OK to log in.
In this scenario, we have included all the necessary information in a single page. The user doesn’t have to flip around, and they can complete the process much more quickly and easily.
But what about the other pages?
Ideally, we would likely still have the other pages present (pages 2-6). The key is that we do not require the user to visit those pages as part of this particular process. The user would go directly to those pages for specific problems, and would find those pages via the TOC or index.
And what about readability?
Is it more wordy? Yes, a bit. But that doesn't have to be a bad thing, if you know how to format your text.
What’s the best way to help readability? Use notes and bullets to make it easier to scan.
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. Look back at the example and you will see how easy it still is to scan, even with the excess information.
The challenge with these types of documents? 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 set up to be flipped through 10 times for one task. That is what online help is for (see an upcoming blog post for more information about that format).
As a writer trying to create a (good) user manual, it is better to divide your content up and present it in a self-contained manner. In this way, ALL of the information necessary to perform that task would be present in that section of content.
Example: Bad formatting
Take this basic scenario of sample pages from a user manual, and see what’s wrong with it:
Page 1
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. Let's take a look at the other pages the user has to visit in order to complete those concise steps on page one.
Page 2
Locating the application
Open the Start Menu and select the application from the list. If you do not see the program listed, go to page 6 for troubleshooting. If you do not know how to access the Start Menu, see page 5.
Page 3
Getting your user name
Your user name is sent to you by your administrator. If you have not received your user name, contact your administrator for assistance.
Page 4
Your user password
Your user password is given to you by your administrator, and you can change it through the Preferences page. Refer to your administrator email for the password, or contact your administrator for more assistance.
Page 5
Accessing the Start Menu
The Start Menu is located at the bottom left corner of the screen in your Windows application. Click it to access the Start Menu.
Page 6
Cannot locate the application
If you have installed the application but do not see it in the Start Menu, contact Customer Support for assistance.
Big problems
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...
Example: Good formatting
Let’s create user manual text that is effective. Here is a better version of the above information:
Page 1
Logging into the application
1. Open the Start Menu, which is located at the bottom left corner of the screen in your Windows application.
2. Locate Application A, and double click to open it.
Note: If you have installed the application but do not see it in the Start Menu, contact Customer Support for assistance.
3. On the login screen, enter your user name.
Note: Your user name is sent to you by your administrator. If you have not received your user name, contact your administrator for assistance.
4. Enter your password.
Note: Your user password is given to you by your administrator, and you can change it through the Preferences page. If you have forgotten your password or aren’t sure what your password is, refer to your administrator email for the password, or contact your administrator for more assistance
5. Click OK to log in.
In this scenario, we have included all the necessary information in a single page. The user doesn’t have to flip around, and they can complete the process much more quickly and easily.
But what about the other pages?
Ideally, we would likely still have the other pages present (pages 2-6). The key is that we do not require the user to visit those pages as part of this particular process. The user would go directly to those pages for specific problems, and would find those pages via the TOC or index.
And what about readability?
Is it more wordy? Yes, a bit. But that doesn't have to be a bad thing, if you know how to format your text.
What’s the best way to help readability? Use notes and bullets to make it easier to scan.
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. Look back at the example and you will see how easy it still is to scan, even with the excess information.
RSS Feed