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.

Why?

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.

Need help growing your business or nonprofit organization?  Browse my website to learn about how I can help you with your particular needs.
2 Comments
 
 
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.
2 Comments
 
 
So you want to be a good technical writer.  Ok.  But what does that entail?  What is good technical writing vs. bad technical writing?

I’ve seen a lot of software engineers attempt to write help documentation.  And a lot of companies try to save on cost by having them do so (not a good idea).  During my career I have learned something very important: technical writing is a skill that must be developed, and not everyone is capable of good technical writing.  And something else I have learned: you need to be a good writer, first and foremost, before you can be a good technical writer.  You must have the skills to not only translate technically challenging information into common language, but to use the English language appropriately in pursuit of this goal.

So how can you become a better technical writer?  Or better yet, want to know some technical writing basics?  Here are some tips.

1.  Know your audience.  Are your end users technically savvy people?  Or are computers completely foreign to them? 

Knowing the answer to this question is important for determining how you need to present your material, and what level of detail you should provide.  If you have a very savvy audience, then you can use more complex ideas and omit some basic information (such as, what a user name is).  If you have a group of users who have never before accessed a computer, then you would need to go into more detail about basic use (i.e., explaining what a user name is) and you would want to omit information that is way above their knowledge level.

2.  Use direct language.  Tell them what to do.  Use “click here to continue” rather than “the button should be clicked to continue”.

3.  Get to the point.  The worst technical documents are wordy, wordy, wordy.  Good technical writers know how to condense their material into the shortest possible sentence/paragraph without losing meaning.  This is not always an easy task, depending on your skill level.  But do make an effort.  For example:

Bad technical writing:  Scroll to the bottom of the page and locate the Submit button, which you will then click to submit your information to the database.

Good technical writing:  Click the Submit button at the bottom of the page to submit your information to the database.

What’s so bad about the first example?  Wordy, bumbling, and indirect (“which you will then click”).  What’s so good about the second example?  Clear, to the point, and succinct. 

You don’t need to tell the user to scroll down if you say that the button is at the bottom of the page.  The user will know they need to scroll in order to get there.  So take it out – it’s a waste of space and words.

More tips to come.
Add Comment