How to write your first user guide

by Editor on September 30, 2011

When’s the last your read a user guide and thought, “Wow, that’s great!” User guides have a bad reputation. Instead of seeing them as something that helps get the job done, many feel that user guides (aka user manuals) makes things more different.

So, how can we write a user guide that:

  • Users want to read.
  • Want to share with others.
  • Helps reduce the cost of technical support.
  • Increases your credibility as a quality provider.
  • Is a pleasure for you to write?

How to structure your User Guide

There’s a saying in sports – fail to prepare; prepare to fail. And the same applies when writing user guides. Before you write a single word, outline the key sections of the guide and then start on each section.

Most novice writers make the mistake of getting pumped full of energy and then ‘going for it’. That’s fine if you want to get something out to customers but, in your enthusiasm, you will probably overlook some of the problems they’re having with the applications.

Let’s step back a moment and look at some the guidelines you need to cover in your document:

  • How to use a style guide for your user guide
  • How to identify the users problems
  • How to format the user guide correctly
  • How to create the table of contents
  • How to use images effectively
  • How to make information easy to find
  • How to write instructions
  • How to publish the manual to pdf, online help and mobile devices
  • How to test the user guide
  • How to update the guide after getting feedback

How to use a style guide for your user guide

Before you start writing your user guide, select one of the industry standard style guides, such as the Microsoft Style Guide for Technical Publications. Then stick to it.

  • No style guide is perfect. But, training yourself – and other writers – to use the style guide will contribute to the quality of your documents.
  • It also takes personal opinion out of the picture and reduces squabbling between writers.
  • When in doubt, consult the style guide.
  • Identify the most frequently used sections in the style guide, for example, how to use bullet lists or write instructions, and print these out.

How to identify the users problems

One way to look at user guides is to think of them as How Do I Manuals.

How I do… solve this problem, find this feature, change the options. Write your user guide with this in mind and your readers will thank you.

How do you identify users problems?

  • Look at technical support queries from customers. What problems do they have most frequently?
  • Ask questions on forums, social media networks, and other areas where you can get feedback.
  • Ask open ended questions, such as, ‘What’s the one thing about our product that gives you the most problems?’ Then explain how to do this in the User Guide.
  • Use the application yourself and identify the tasks you need to complete to use it effectively.

Once you have done this, create a master list of questions (i.e. problems) that the user needs to understand. This is the foundation of your user guide.

How to create the table of contents

There are several ways to create the table of contents for user guides. One consideration is which target readership you’re writing for. In other words, are you writing for:

  • Beginners
  • Advanced users
  • Power users

Here’s the problem:

If you write for beginners, where do you put the material for the more advanced users? One way to do this is to create a standard ‘hold all’ table of contents at the start of the document… and then add a power users section at the end.

Remember, most users don’t read the manual from start to finish. Instead, they look for what they’re trying to fix, locate it, and then read that page only.

With that said, you still need to create a table of contents. Here’s one approach.

  • Identify the high level activities involved in using the application, for instance, setting up, getting started, using features, and configuring the software.
  • Use these to create the main chapters in the document.
  • Then, drill down and outline the main tasks for each chapter. In Getting Started, identify the tasks they need to complete to get the software up and running.

Numbering Conventions

Create a consistent naming convention for all sections. For instance, use 1.1, 1.1.1 and 1.1.1.1.

To be honest, I rarely go down to 1.1.1.1 as it creates problems with MS Word and also makes it hard for the reader to find information when searching online documents or using the index. Stick to levels 1.1 and 1.1.1 if possible.

How to use images effectively

Let’s look at the role of screenshots in user guides. One of the mistakes novice technical writers make – or those who are new to writing user guides – is to include screenshots on as many pages as possible.

Here’s a better approach when adding images to user manuals:

  • Add screenshots that SHOW a procedure that may otherwise confuse the reader. A good example is where they are ‘floating windows’ and it may be hard for the user to tell which window to click on.
  • Add screenshots that provide granular details, for example, if an option is hidden or hard to find in the user interface.
  • Add screenshots the show the correct option, for example, in a drop down menu. Without the screenshot the user may not see this option.

What you shouldn’t do is add screenshots that:

  • Increase the page count.
  • Clutter up the document.
  • Make other information harder to find.
  • Frustrate the user who keeps getting distracted by this eye candy.

To make sure you – and your team – use screenshots correctly:

  • Establish guidelines for taking screenshots.
  • Don’t capture the entire desktop unless you need to.
  • Focus on what action the user needs to complete.
  • Crop the screenshot and remove any noise that may distract them.
  • Add the image to the user guide next to the correct text.
  • Include a caption.

How to format the user guide correctly

The next step is to format the user guide. What this means is that your final draft will:

  • Have the same look and feel.
  • Use the same fonts across all sections.
  • Have the same size/design for screenshots.
  • Use the same color schemes.
  • Have the same page size. This can change if you copy/paste large text blocks from other documents.

In addition to the ‘cosmetic’ side of the user guide, i.e. how it looks, you need to format the document on other levels. Check that it:

  • Uses the same version of English, e.g. UK v US English.
  • Uses the same numbering system.
  • Has consistent headers and footers.
  • Follows a logical order in the table of contents.

How to make information easy to find

Your document is there to help users solve problems. One way to do this is to help readers find the answers to their questions fast.

While finding these answers may seem obvious to you – after all, you’ve lived with the document for weeks – for others finding this information may not be so easy.

For instance, if they can’t find it in the table of contents, then where should they go?

You can make information easy to find as follows:

  • Add keywords to the section headings. Keywords are words users are likely to use when searching for answers
  • Remove filler or obscure words from your headings, section titles and table of contents
  • Create an index. Add the critical terms here.

NB: Remove terms that clog up the index. While valid in their own way, they make it hard to user to find the more critical terms.

You can further refine the user guide as follows:

  • Create a one page cheat sheet. Answer the most frequently asked questions here.
  • Organize the information in a hierarchy. Think of a pyramid with the most important tasks at the top.
  • Divide the document into sections by frequency of use.
  • Divide the document into sections by level of expertise.
  • Use colors, shading, underlines etc to highlight importance.
  • Create a list of keywords and use these to build your index.
  • Add synonyms to the index. For example, in the US it’s called an elevator. In Europe, it’s a lift.
  • Include a glossary of terms.
  • Include a trouble-shooting section and a list of frequently asked questions.

How to write instructions

The difference between writing user guides and other type of documents is this. When writing a user guide, think in terms of ‘How Do I…’

  • How do I install the software?
  • How do I find the option to change channels?
  • How do I change security settings?

And then answer these questions.

If you write your user guides from this angle – and avoid filling out the document just to increase the page count – your readers will find your document more useful and rely on it for their answers.

One practical way to do this is to learn to write instructions:

  • Identify the problem.
  • Describe the pre-requisites that may need to perform.
  • Give step by step instructions on how to solve the problem.
  • Include notes, warnings or alerts where necessary.

When writing the instructions, follow these guidelines:

  • Use the ‘you’ convention when writing.
  • Write the sequences in the correct order.
  • Write in the present tense. Users are using your application right now!
  • Write in the active voice. Be clear about who does what.
  • Keep sentences short. Avoid waffle.
  • Number the steps (e.g. Step 1, Step 2 etc.)
  • Describe the purpose and meaning of symbols, icons and codes at the start of the documents.

Mistakes to avoid when writing instructions:

  • Don’t say ‘one should’ or other dated writing styles. Write in everyday language.
  • Don’t write long paragraphs.
  • Don’t use jargon, cliches or industry terms. Also called TLAs. Three Letter Acronyms
  • Don’t patronize the user.
  • Don’t assume the user has prior experience or knowledge of how your product works. Give them some background information and point them to knowledge bases if necessary.

How to publish the user manual

Once you’ve completed the user guide, you need to publish it in a format that suits the reader.

In general, this means converting the user guide to:

  • PDF
  • Online Help
  • Formats for mobile devices

Be careful when converting your documents to these formats as each one has its own limitations and issues.

For example…

When converting your user guide to PDF, make sure the:

  • PDF opens at the correct screen size.
  • Includes the correct table of contents.
  • Has a consistent look and feel, especially regarding page size and layout.
  • Fonts render currently.
  • No error messages appear when you open the PDF on different PCs or web browsers.

When converting your user guide to online help, make sure the:

  • Index is correct and reflects the table of contents.
  • Keywords are added to the index. Negative keywords are removed.
  • Images appear correctly. If you use the ‘wrong’ file formats, they may not appear correctly onscreen.
  • The navigation makes sense to the reader.
  • Search works correctly and gives the right results.

When converting your user guide for mobile devices, make sure the:

  • Pages download quickly.
  • Font size is easy to read.
  • Images appear correctly and don’t align above/below the text.
  • Search option works correctly.
  • Links to other sites are correct.
  • Contact information is correct and works.

How to test the user guide

Before you release your user guide, you need to check that it works, right? Otherwise, you can’t tell if it solves the reader’s problems.

How do you test the user guide?

  • Share the document with a series of test users.
  • Ask them to perform specific tasks.
  • Monitor how they find this information in the user manual.
  • Observe how to follow the instructions to accomplish these tasks.

How to update the guide after getting feedback

After you’ve done this testing, revise the text where necessary.

  • Update the user guide version number to reflect this change.
  • Release the new ‘final’ version.
  • Archive the previous copies.
  • Remove them from share drives, networks and other locations.

Conclusion

Creating a user guide is a wonderful way to help others use your software or service. As it’s most user’s first port of call, it creates a deep impression on how they view your company. So, take your time and make sure the user guide solves their problem as quickly as possible.

While other guides are written for sys admins, developers, and testers, this is specifically for Customers. Instead of calling it a User Guide, see it as a Customer Guide. And you want your customers to be happy, right?

Have a problem writing your user guide? Drop me a line and see if we can help.

Comments on this entry are closed.

Next post: