Procedures are the core part of user assistance. A procedure is a description of the steps that users have to follow to complete a specific task.
▪A procedure typically begins with an introductory phrase that states the goal of the procedure and ends with a colon. Sometimes the introductory phrase can also be a statement, which ends with a colon or period. ▪Steps are numbered. They consist of action statements, descriptions of the system’s response, and related information that enable users to execute the procedure. ▪The procedure typically ends with a brief description or picture of the result. |
Yes:
|
To set the alarm time:
1.Hold down button A for at least three seconds.
The time display now blinks and shows the currently set alarm time. 2.Press the arrow buttons repeatedly to change the alarm time. 3.Press button B to store the new alarm time.
The new alarm time now appears at the bottom of the display after the chime symbol. |
Yes:
|
Writing a manual involves three major tasks:
1.Planning the structure. 2.Designing the template. 3.Writing the texts. (Strictly speaking, this is not a classical procedure but a process description. The introductory phrase is a statement, although it also states the goal (writing a manual). The steps aren’t written in an imperative form.)
|
Expand /Collapse All Subsections
Never use body text for procedures. Always use numbered steps.
Don’t use words to describe the succession of steps, such as “first,” “next,” “in the following step,” and so on.
Don’t merge multiple actions into one step.
No:
|
To change the brightness of the screen, you first need to press the red button. The value of the current setting then appears on screen. Next, press the arrow keys to change the brightness. When you’ve finished, finally press the green button. The new brightness value is now set.
|
No:
|
To change the brightness of the screen:
1.First, press the red button. The value of the current setting now appears on screen. Next, press the arrow keys to change the brightness. When you’ve finished, continue with step 2. 2.Finally, press the green button.
Congratulations! The new brightness value is now set. |
Yes:
|
To change the brightness of the screen:
1.Press the red button.
The value of the current setting appears on screen. 2.Press the arrow keys to change the brightness. 3.Press the green button.
The new brightness value is now set. |
Talk to readers clearly and directly and use the imperative.
No:
|
The next step consists of pressing the Stop button.
|
No:
|
One must press the Stop button now.
|
No:
|
Now the Stop button should be pressed.
|
No:
|
Now it’s necessary to press the Stop button.
|
No:
|
Now you need to press the Stop button.
|
No:
|
Now you must press the Stop button.
|
No:
|
Now, please press the Stop button.
|
Yes:
|
Press the Stop button.
|
Describe only the simplest, most common way of doing things. When documenting software, describe keyboard shortcuts in a separate reference topic of shortcuts.
No:
|
Click File > Save. Alternatively, you can also press [Ctrl]+[S].
|
Yes:
|
Click File > Save.
|
If a procedure involves any hazard, add a warning directly before the step that involves the hazard (see Writing warnings). Don’t add the warning after the step.
If a warning relates to the procedure as a whole, add the warning at the beginning of the procedure.
Keep procedures as short as possible. If a procedure has more than 7 to 10 steps, consider splitting the procedure. If it’s not possible to split the procedure, add labels (subheadings) that group steps into subtasks or that mark certain milestones in the procedure.
|
Don’t assume that the correct conditions are already in place.
▪With products that involve navigation through menus, don’t assume that users already are in the right place to start a procedure. They could be anywhere within the on-screen menu when reading your instructions. ▪In a service manual, don’t assume that users have already disassembled certain components or have already completed other preparatory steps. ▪Bear in mind that users may have done something that will prevent the procedure from working. Consequently, clearly state all prerequisites at the beginning of the procedure. In addition, if any special tools are required, list these tools so that users can fetch them in advance.
Often, the best way of stating the prerequisites is to make the preparation the first step of the procedure (“1. Make sure that you have … available.”, “1. Prepare ….”).
Alternatively, you can formulate the prerequisites as a condition that you put before the steps (“You must have … before ….”). If you have a large number of prerequisites, put them into a table or list.
If you have various similar procedures, state the prerequisites in a consistent, parallel way. For example, always use a table, and always use the same structure within this table.
|
Don’t hesitate to explain the purpose of a step. People are often more willing to execute a particular step and perform it better when they understand why they need to do it. Half a sentence is often enough.
No:
|
…
5.Fix the bolt with a small piece of adhesive tape. …
|
Yes:
|
…
5.To prevent the bolt from falling down, temporarily fix it with a small piece of adhesive tape. …
|
|
To give users the possibility to control the success of their actions, describe not only the users’ actions but also what happens as a result of critical actions. Feedback is especially important if many of your readers are inexperienced users.
Sometimes you can embed the information about the response right into a step. If that’s not possible, add a line break, and then add a second sentence.
Yes:
|
1.Click Options to display more fields. 2.Select Landscape. |
Yes:
|
1.Click Options.
The dialog box expands. 2.Select Landscape. |
If the change of state has important negative implications, include these in a note or important note (see Writing notes).
At the end of the procedure, describe or show the final result.
|
Make it easy for readers to follow your instructions step by step. Get your words into the same order that users must follow both mentally and physically.
Match the order of words with the sequence of steps that users must take to identify an object. Always tell users where the action takes place before describing the action to take.
No:
|
Click Save in the Options window.
|
Yes:
|
In the Options window, click Save.
(Users must first find the Options window, then find and click the Save button.)
|
|
Usually, create one sentence for each step. This breaks down a complex task that’s difficult to perform into a number of simple subtasks that are easy to perform. In addition, it helps you to bring the information into the right order.
Avoid “do-this-after-you-have-done-that” statements.
No:
|
To write a user manual, enter the text into the previously opened word processor, according to the structure of the outline that you’ve set up before beginning to write.
|
Yes:
|
To write a user manual:
1.Set up an outline. 2.Open your word processor. 3.Enter the text according to the structure of your outline. |
It’s OK to combine two steps if:
▪both steps are short ▪both steps occur in the same place or affect the same component
Yes:
|
On the Tools menu, click Options, and then click the Edit tab.
|
Yes:
|
Insert the probe holder and turn it clockwise until it snaps into place.
|
Note that the word then is not a coordinate conjunction and thus cannot correctly join two independent clauses. Always add “and.”
No:
|
On the Tools menu, click Options, then click the Edit tab.
|
Yes:
|
On the Tools menu, click Options, and then click the Edit tab.
|
|
Make sure that each numbered step contains at least one action for every reader. For this reason, optional steps shouldn’t have their own number.
Always start with the most common (default) action, followed by the alternative action.
For choices within one procedure step, use a list.
No:
|
…
7.If you live in Europe, enter EUR. 8.If you live in America, enter AME. 9.If you live in any other part of the world, enter GLOB. …
|
Yes:
|
…
7.Enter your region code: ▪If you live in Europe, enter EUR. ▪If you live in America, enter AME. ▪If you live in any other part of the world, enter GLOB. …
(Note: This example assumes that the product is mainly sold in Europe, so Europe is the first item in the list.)
|
Put the if-condition at the beginning of the sentence so that readers for whom the condition isn’t fulfilled can skip the rest of the sentence.
No:
|
Open the cover and check that a color cartridge has been inserted if you want to print in color.
|
Yes:
|
If you want to print in color, open the cover and check that a color cartridge has been inserted.
|
|
When users have to repeat one or more steps multiple times, you often can’t avoid having a loop within your procedure.
Always loop to something recognizable, like a step number.
Yes:
|
…
7. Repeat steps 3 through 6 until ….
…
|
Note:
Looping to a step number is usually the most user-friendly solution because this clearly identifies the beginning of the loop at a glance. However, bear in mind that this solution is also very error-prone. If you add or remove a step from the procedure later, the step numbers will change. You must then also change the loop information, which you can easily forget to do.
|
Precede all procedures with colons, regardless of whether the text before the colon is a complete sentence or partial sentence.
Note:
Microsoft recommends that you don’t use a colon or any other punctuation here. If you want to create documents that mimic Microsoft user assistance, omit the colon.
Use sentence-style capitalization for each step.
Add a period at the end of each step. Don’t use exclamation points.
|
Sometimes, step-by-step procedures aren’t the right means to communicate a task.
Flowcharts:
If a procedure is essentially a decision-making process rather than a straightforward action, consider using a flowchart. A flowchart graphically shows the decision points and the pathways that users must follow through the branching logic of the procedure.
In particular, flow charts are often a good choice for troubleshooting and repair procedures. If the results of the decision tree are recommended actions, you can link to detailed step-by-step procedures from the flow chart.

Play script format:
If a task involves various stakeholders, a play script format can be a good choice. Often, such tasks are administrative tasks within an organization.
Each person’s actions are listed separately, so each person clearly sees which steps must be done by him or her, and also sees the global context of these actions in the whole procedure.
One column lists the actors; the other column lists the corresponding steps.

|
|