Sharp Words

Technical documents can be loosely divided into two types: the informational and the procedural. Each has its place, but I don’t think it’s an exaggeration to say that a nicely numbered How To procedure can be far more useful for a reader who just wants to know how to get something done and doesn’t necessarily care about the why and wherefore, or what the other buttons might be used for.

Here are my golden rules of writing a How To. Some of these apply generally to technical documents as well!

Introduce your How To.
A procedure should be introduced by something like ‘How to edit a document‘ or ‘To set colour options:‘
If there is any information that’s essential for the reader to know about the procedure, this should be included either directly before or after the introductory heading. This information could be something as straightforward as a particular mode they need to be in or permissions they need to have, or more importantly, a warning that they need to disconnect a device from the mains electricity.

Number your How To.
Using a numbered list indicates to the reader that these are steps which should be followed in a particular order.
Of course, if it doesn’t matter what order the steps are done in, then use bullet points instead. But arranging the How To in a list format makes it easier to follow.

Keep your How To simple.
If you find you’re trying to explain too many varied options in a procedure, with convoluted sub-procedures sneaking in every couple of steps, break the main down into smaller, separate ones. They’re easier to read, and easier to write as well (particularly if you use a tool that can deal with content re-use).

Write actively.
Be decisive about the instructions you’re giving (use the imperative), and write as much as possible in the present tense.
Use sentences such as ‘Click the Big button to open the Little dialog box‘ rather than ‘If you click the Big button, the Little dialog box will open‘.
Try and avoid use of the passive if possible – sometimes it’s ok to use it, of course, when not to do so makes a sentence more complicated than it needs to be.

Write positively.
Tell readers to do things, not to not-do things. For example, use ‘Save your work, then close the application‘ rather than ‘Do not close the application without saving your work‘.

Use consistent terms.
Always refer to bits of the software or hardware by consistent terms. Don’t call something a ‘drop-down list‘ in one part of the procedure and then refer to a similar bit of the user interface as a ‘combo box‘ later on.
Keep your phrasing consistent too. For example, use either ‘From the File menu, select Save‘ or the alternative ‘Select Save from the File menu‘ throughout a procedure; don’t mix them. (That’s helpful if the documents are translated, too!)

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts