Five Tips for Writing a User Manual


*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

A successful user manual provides quick answers to questions that users might have about how to complete tasks. Technical writing focuses on the tasks along with the concepts that support them.

Here are five practical tips on writing user manuals.

Think like a user

You should have a good understanding of your users so you can understand the information they need to know, how they approach each task, and when they might use approaches to tasks that are unexpected.

Use active voice

Sentences that use active voice emphasize the user and are easy to read and understand. In active voice, the subject and verb in the sentence are clear. In passive voice, the subject is unknown and is acted upon by something that is not known or not stated. Passive voice uses verbs that include a form of “to be”.

Focus on the reader

When writing information that involves the reader, such as instructions, pull readers into the document by using “you” to make the content relevant to them.

Compare the two sentences below.

Reader focus: You can choose from one of three options for viewing content in the editor. 

Lack of reader focus: There are three options for viewing content in the editor.

The sentence that uses “you” makes it clear that the reader is the person doing the action.

Write clear instructions

The primary objective of user manuals is to help users complete tasks. Here are some guidelines.

  • Use numbered lists for instructions, unless the instruction includes a single step.
  • Use parallel construction for each step. Typically, you should start each step with an imperative word that provides clear cues.
  • Avoid using a system response as a step. For example, don’t say, “The Info dialog window opens” as a step. Mention the system response at the beginning of the following step (for example, “In the Info dialog window…”.
  • Provide just enough information so that the user can complete a task or understand a concept. Concise content makes it easier to understand concepts and tasks. 

Establish standards

When creating documentation, there will be areas where there may be more than one way to spell a word, refer to an object, caption graphics, punctuate sentences, lay out a page, and organize information. Establish standards by making decisions for users beforehand.

In addition, use an established style guide, such as The Chicago Manual of Style and Microsoft Manual of Style to establish some specific guidelines for your writing project.

Have something to add? Please share it in the comments.

Getting to the Point When Writing for the Web

By Leslie Brown

Writing web copy is different than writing copy for print material. I’ve written both, and here are some of the things I’ve learned from different sources about writing for the web.

Readers take only seconds to assess whether a web page is worth pursuing or not, so you can’t linger on a thought. Get to your point quickly by making each word count.

1. Keep it short.

  • Use short words, short sentences, short paragraphs, and short pages.

2. Keep it simple.

  • Include only one or two ideas in each short paragraph.
  • Use simple language and common words so readers have to scan less to determine what a page is about.

Continue reading

Some Best Practices When Writing Help Documentation


*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

If you are planning to create online help documentation and want to make sure you end up with one that is truly helpful, here are three best practices you can follow to make sure it is:

  • Tailor it to users who have with varying skill sets and goals.
  • Review, test, and update it for accuracy.
  • Create context-sensitive topics.

Keep different users in mind

You can’t always predict what every user will know or want to know about any product. On one hand, if you oversimplify help steps, users might get confused. If you provide too much detail, they might get frustrated or bored.

One way to alleviate this problem is to divide help topics into several different types that target users at different skill levels by varying the kind and amount of information you provide. For example, you might have an overview topic, such as a definition of a specific system function, and then provide a link to all of the tasks related to that function within the overview. That way, users get just the specific steps they want.

The key is to allow users to navigate the help documentation to find (or avoid) as much detail as they want.

Continue reading