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 format a user manual

2/11/2011

2 Comments

 
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.

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.
2 Comments
lee link
2/19/2011 04:40:17 am

Well said; well done.

An issue which will undoubtedly come up, though, is simply 'real estate'--especially for print.

Your analysis is quite good, and is great advice for producing on-line-type documents.

As you allude to (with 'page flipping'), though, on paper the possibilities are a bit more limited: You can note-and-bullet all day, but pretty soon, you've got half your page filled with notes and bullets.

This is a great thread; I daresay it might be good to discuss use of the available space on a printed page.

Thank you!

Reply
Gunnar Gustafsson link
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...

I have had to do it for a document not initially prepared by me... it was a complete nightmare and I finally got approval to rewrite the whole document...that was the only way to solve the problem.

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

Copyright © 2016 WriterLiz, LLC. All Rights Reserved.
  • 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