*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.
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.