Writing User Manuals: Five Top Tips

Writing User ManualsWriting user manuals is a common requirement of the technical writer’s role across many different industries. It’s also not uncommon for this task to fall to someone who is not a technical writer by trade — and in this case, writing user manuals can seem like a daunting task. We’ve drawn on our expertise in this field to put together a list of five top tips to keep in mind when you are writing user manuals:

Know the End User

Who is the end user? This is most important question to ask before you begin drafting your user manual. To write a user-friendly user manual, you need to think like your user. To do this, ask yourself the following questions:

  • Is the end user familiar with your product or products like it?

If they are familiar with your product, don’t over explain things that they already know, as this will make the content of your user manual seem tedious to them. In contrast, if your end user has never used your product or products like it before, they will need much more detail about the basics of what the product is. In cases where the user guide contains different sections to cater to multiple users with varying levels of experience, you should find a way to let the user know which information is relevant for them. For example, you could place icons representing each level of user beside the section of text that is relevant for them.

  • How technically skilled is the end user?

This will affect things like the terminology you use, for example, an engineer will understand highly technical terms, whereas someone with less technical knowledge will need simplified terms and explanations of technical terms. If your user manual is aimed at the general public, you need to consider the general public’s varying levels of literacy and ensure that the user manual is easy to read for the majority of the general public. Similarly, if you are writing a user manual aimed at children, you need to ensure that they can understand the language you are using. It can be helpful to use readability scores such as Flesch-Kincaid to ensure that the readability level of your user manual is appropriate for the end user.

  • What does the end user need to know?

A user manual should provide the information that the user needs. The user manual shouldn’t include any information that the user does not need. For example, if a device has one user manual for a skilled installation specialist, and one for an unskilled end user, then the manual for the unskilled end user — who does not need to know how to install the device — should not include the installation information. You should also give prominence to core everyday tasks such as troubleshooting common user problems.

Make the Content Easy to Scan

It is important to make sure that content is easy to find and that the user can scan the manual quickly to find a piece of information. Generally, users don’t sit down and read a user manual cover to cover. Instead, they read it when they need to find a particular piece of information, so make it easy for them. For example, a field engineer may need to access a particular piece of troubleshooting information quickly to rectify a problem on site, which means that they may be in very trying circumstances and so do not have time to sieve through the user manual to find the required information.

You can increase the scannability of your user manual through document structuring and formatting. Give sections and subsections clear names and list them in a table of contents at the start of your manual, so that a user can easily locate the section they need. Make important information stand out so that it can catch the reader’s eye while they are scanning the document, for example, you can make UI items bold.

Similarly, you should make warnings and notes stand out. You can draw attention to warnings and notes by separating them from the main text and adding appropriate warning and note symbols beside them. You can also increase the scannability of your user guide by avoiding long paragraphs of text. Long unbroken paragraphs of text can be difficult for a user to read; avoid using long paragraphs by using tables and lists to present content instead.

Maintain Consistency

Be consistent with your use of language, formatting, and graphics throughout the user manual. Maintain the same tense, preferably the present. You should also be consistent with spelling. If you are writing in US English, ensure that you do not use any UK English spelling conventions, and the other way around. Similarly, you need to be consistent with the terminology you use. Don’t use multiple different words to describe the same thing, for example, using mobile, cell phone, telephone, phone, and so on, to describe the same item. This can be confusing to the reader and they may think that you are referring to multiple separate things. This is especially true for readers whose first language is not English. It is also important to be consistent with the formatting you use in your user manual, for example, if you have been using bold type for UI items, don’t switch to using italic type half-way through the document. This will look bad and can be confusing for the reader.

Use Graphics

Be sure to use graphics throughout your user manual. Graphics help to break up blocks of text and keep the reader interested. They are also a useful point of reference for the user when it comes to following instructions. For example, if you are giving the user instructions on how to complete an action within a software tool, it is helpful to include screenshots so that the user can see exactly where UI items are located. Similarly, if you are telling a user to press a button on a hardware device, they need to know where that button is located and what it looks like. You should also make sure to clearly name and label your graphics so that they make sense in relation to the text.

Graphics can be a great addition to a user manual, however, don’t over-use graphics or add in graphics that don’t add any value to the user manual. Similarly, you should take care not to overuse screenshots and only use them where they add value. Choose the screenshots that you include carefully. For example, rather than including a screenshot showing an unpopulated UI window, it would be more beneficial to the user if you include a screenshot showing a more complex scenario so that the user can see how this scenario appears in the system.

You should also be careful with adding text within graphics as this can make localisation difficult. For example, if you are using callouts to show various parts of a device, you should use numbers rather than words in the graphic and then provide a table explaining what each number represents below the graphic. This helps when it comes to localisation, because if the graphics have numbers instead of text, you won’t have to have the graphics localised. This will save you time and money.

Present Procedural Information in Ordered Lists

Be sure to use ordered lists whenever you are writing instructions. This is probably one of the most important factors when it comes to writing user manuals. Paragraphs of text can be intimidating to users, and often, the user will have to read the paragraph more than once to understand its meaning. You want the user to follow the instructions and you want them to do it right, so make it easy for them. Break your instructions down into individual steps and list them clearly and in the correct order. Don’t forget to arrange your steps in the order in which they should be completed. Look at the text below:

Go to the TWi blog by clicking on the blog button on the TWi homepage that you got to by putting https://www.technicallywriteit.com in the browser navigation bar. Then you can open up the blog post that you want to read.

Now look at the following text:

To read a blog post on the TWi website:

  1. Open your web browser.
  2. Type https://www.technicallywriteit.com into the navigation bar and press Enter.
    This opens the TWi website homepage.
  3. Click the BLOG tab in the top menu bar.
    This opens the blog page.
  4. Click on the heading of the blog post you want to read, or click the Continue Reading button at the bottom of the blog post summary.
    This opens a page containing the full blog post.

It is clear which set of instructions are easier to follow. The first example is confusing. The instructions are not in a logical step-by-step order and need to be re-read multiple times before the steps are clear. In contrast, the second example is direct, shows the steps in the order that the user should perform them, and lets the user know the results of their actions.

To summarize, no matter what your product is, you will need to write a user manual for it, and it is important to ensure that your user gets the most out of your user manual. Keep the five tips above in mind when you are planning and drafting your user manual and you will be on your way to writing a great user manual.

Did we miss anything important? Tell us your thoughts in the comments!

HAVE SOMETHING TO SAY?

If you’d like to share your thoughts or know more about this topic, complete our feedback form. We look forward to hearing from you!

Please follow and like us:
error

, , ,

2 Responses to Writing User Manuals: Five Top Tips

  1. Mike Unwalla June 28, 2019 at 8:16 am #

    What methods and software do you recommend for making sure that documents are consistent?

    • TWi
      TWi July 1, 2019 at 10:12 am #

      Hi Mike,
      Having a well-developed style guide that you stick to consistently is invaluable. We also find that quality review circles help to promote knowledge and use of a style guide across writing teams.
      More fundamentally, having a well-defined information architecture in place is essential for keeping large documentation sets consistently structured.
      We’re sure you have some preferences as well – what are your thoughts?

Leave a Reply