Navigation in instructions
From TechWriter Wiki
Contents |
Introduction
Although the subject of navigation in general is discussed in Navigation, additional care should be taken when considering navigation within instructions. Users are typically reading the instructions at the same time as they perform the task (especially for embedded help). You should therefore provide a linear narrative, branching at the relevant points.
Provide a clear, linear path
Never assume that the reader will read through the entire document before deciding which parts of it they need to carry out. You should always assume that the reader will follow your instructions blindly, and to the letter. You can normally assume that if you provide a numbered list of steps that the reader will carry them out one after the other, in the order shown, but that is about it. For instructions of more than one page, or where there is any kind of variability (such as conditional steps) it is absolutely imperative that clear navigation is provided.
A useful exercise to perform, to confirm that you have provided adequate navigation, is to draw a flowchart of the paths through the document. Include every branch and decision on this, and you should be able to identify whether you ever send the reader off down one path without directing them back into the main flow.
Differentiating between options
If it is necessary for the user to carry out (for example) only one of four possible options, then you should explain this before describing any of the options. In this case, it is also sometimes advisable to state clearly that the reader should read all four options before deciding which one to choose. Otherwise, users have a tendency to pick the first option that is a close enough approximation to their needs, potentially ignoring a `better fit' option that is listed after this option.
Example
| Avoid | Use Instead |
|---|---|
You can:
| There are four actions you can take for the request. Read through the possible actions below, and then carry out the one that best reflects what you want to do:
|
Navigating around options
Always assume that the user will progress through the document from start to finish in a purely linear manner, unless they are explicitly told to do otherwise. This means that it is necessary to specifically guide users around optional sections of the instructions when they do not need to carry out those options.
Do not assume that users will inherently know, or automatically work out for themselves, whether or not they need to carry out anygiven optional section - you should specifically ask them to make this decision. Bear in mind that quite often users are referring to the documentation as a last resort when they are in trouble (something is not working the way it should) they are likely to be under pressure and lacking the time or patience to mull things over.
Example
| Avoid | Use Instead |
|---|---|
| 2. Change the order items 2.1 Add an item
2.2 Delete an item
| 2. Change the order items 2.1 Decide what to change
2.2 Add an item
2.3 Delete an item
2.4 How to continue "Continue with "3. ..." |
Note:
An alternative - but less satisfactory - solution would be to explicitly state in the lead-in sentence for each block that this is an 'optonal' block and identify the circumstances under which it should be carried out. For example, use "If you want to add an item then you can do so by following the steps shown below" for option 2.1 on the left, and "If you want to delete an item then you can do so by following the steps shown below" for option 2.2 on the left. However, as this approach necessitates the user scrolling down (and reading every block as they go) to determine from where they should continue, this approach is discouraged.
