How to write user-interface instructions

User-interface instructions are the step-by-step instructions for doing something like testing software or installing a Windows application. These kinds of instructions are often hard to use. They are frequently incomplete and ambiguous, which makes it easy to get lost in a long sequence of steps, and slows you down by forcing you to make guesses at certain steps. This happens because the writer underestimates how much detail is required, or is just lazy.

This article is a simple description of how to write better instructions that are complete, consistent and easy to follow. The solution is to shift effort from the reader to the writer, by adding detail to the instructions, while having a consistent structure and style that prevents the extra detail for being lots of extra work for the writer.

How to write instructions

Here is what you have to do.

Structure instructions as a single numbered list of steps, or actions.
Provide context at the start of every step, by explicitly identifying the current location in the application, so you do not lose your place when following the instructions.
Specify every single keystroke and mouse click, to remove ambiguity about what the writer should write and what the reader should do.
Use text styles to separately identify user-interface text, and text to type in.

This clearly involves writing more text, and in that sense it is more work. This is worth it if you are writing instructions that you expect someone else to be able to use, because it will save them a lot of time that would otherwise be spent on guesswork. Besides, instructions may actually be faster to write using this approach, because you systematically document everything in a consistent format, without needing to stop and think about what to write next.

Specify a location

Providing context means telling the reader where they need to be before you tell them what to do. Start each step with a phrase like:

On the Log-in page, …
On the Are you sure? confirmation dialogue, …
On the Licence agreement wizard page, …
On the Page set-up dialogue box, on the Margins tab, in the Top field, …

Note that the location name is in a different text style, to make it clear what to look for. This should be the exact text used in the user-interface. The instruction also explicitly says whether you should be looking at a window, dialogue box, alert, web page, tab, form or something else.

If the instruction specifies a nested location, the parts are in the order you find them in the user-interface, so you can read the instruction from left to right. This is why the last instruction is better than:

In the Top field on the Page set-up dialogue box’s Margins tab, …

It makes sense to omit the location if it is the same as the previous location, as with:

On the Print dialogue box, in the Number of copies field, enter 10.
On the Print dialogue box, click the Print button.

Specify an action

After you have told the reader where they should be, you then tell them what to do. This generally involves selecting a value, entering a value, or clicking a button. For example,

In the Layout section, select landscape.
In the Top margin field, enter 10.
On the Print dialogue box, click the Print button.

Again, note the distinction between text in the user-interface, in italic, and text to type in, in bold. Also, note that 'click the OK button' reads better than 'click on the OK button'.

It may seem reduntant to write 'click the Delete button', or 'click the Delete link', instead of just 'click Delete'. However, this extra information saves time for the reader, who will complete their task faster if they know exactly what they are looking for on-screen, not just what the text is.

Do not leave out any steps

It may seem redundant to include the following step (from the Eclipse plug-in installation instructions) because it is obvious what you need to do:

On the Feature licence wizard page, select I accept the terms in the licence agreement, and click Next.

However, a step like this helps the reader remember where he is. It also frees the writer from trying to decide whether or not a step is important enough to include, and then incorrectly excluding it.

Combine simple steps

Sometimes it makes sense to combine simple steps, especially for closing dialogue boxes and submitting forms. Consider two separate steps:

On the Print dialogue box, in the Number of copies field, enter 10.
Click the Print button.

You can combine these as:

On the Print dialogue box, in the Number of copies field, enter 10, and click the Print button.

Conclusion

You can now write far more effective user-interface instructions for use by other people. If you managed to follow the steps, that is.