WriterLiz, LLC
  • Home
  • Services
    • Copywriting
    • Websites & SEO
    • Blogs & Articles
    • Technical Writing
    • Medical Writing
    • Training
    • Photography
  • Testimonials
  • Portfolio
  • Clients
  • About
    • About Elizabeth
    • Formal Resume
  • FAQs
  • Blog
  • Projects
  • Personal Creative Work
  • Contact Me

Blog

How to write in a "user manual" format (expanded version)

11/21/2009

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
jimgf
1/8/2010 12:51:03 am

Nice article Elizabeth.
I found it while searching for how to write good user manuals.

Reply
Elizabeth (site administrator)
1/8/2010 12:56:44 am

I'm very glad the article was helpful for you!

Reply

Your comment will be posted after it is approved.


Leave a Reply.

    Contact me at info@writerliz.com.

    Welcome to my blog.  Please use the Category links below to find topics of interest to you, or just scroll through current postings.
    Share

    RSS Feed

    Receive new postings via email:

    Enter your email address:

    Delivered by FeedBurner

    Categories

    All
    General Writing Tips
    Grammar Mistakes
    Hiring A Writer
    Marketing
    Money Matters
    Nonprofits
    Starting A Business
    Starting A Business
    Technical Writing
    Training/instructional Design
    Websites And Content

    Archives

    November 2014
    June 2014
    May 2014
    April 2014
    March 2014
    January 2014
    December 2013
    November 2013
    October 2013
    September 2013
    August 2013
    July 2013
    May 2013
    June 2011
    April 2011
    March 2011
    February 2011
    January 2011
    November 2009

Powered by Create your own unique website with customizable templates.
  • Home
  • Services
    • Copywriting
    • Websites & SEO
    • Blogs & Articles
    • Technical Writing
    • Medical Writing
    • Training
    • Photography
  • Testimonials
  • Portfolio
  • Clients
  • About
    • About Elizabeth
    • Formal Resume
  • FAQs
  • Blog
  • Projects
  • Personal Creative Work
  • Contact Me