A well-written procedure has a precise effect: a person who has never carried it out reaches the result without asking for help. It sounds like a modest goal, but most instructions circulating in offices do not achieve it. Steps that seemed obvious to the author are missing, button names do not match those on screen, warnings appear after the action they were meant to prevent.
Writing instructions is a skill with clear rules, and it can be learned.
Before writing: who, what, from where
Three questions define the procedure:
- Who will carry it out? An experienced colleague, a new hire, a customer? The level of detail changes completely.
- What is the end result? One verifiable sentence: «the mailbox is set up on the phone and receives messages».
- What is the starting situation? What must already be in place: access rights, installed programs, available files.
The structure
Title: verb + object («Set up company email on your phone»)
Goal: one or two sentences.
Before you start: prerequisites and what to have at hand.
Estimated time: if it helps to know.
Numbered steps.
Result: how to tell that everything went well.
If something does not work: the most likely problems.
A title starting with a verb («Set up», «Restore», «Export») makes the procedure easy to find: people searching are looking for an action.
The rules for steps
1. One action per step. «Open the settings, choose Accounts and tap Add» is three steps. Separating them helps readers keep their place.
2. The verb first. «Click Save» is more immediate than «The Save button should be pressed».
3. Context before action. «On the Security tab, turn on Two-step verification». Readers look for the place first, then the object.
4. Exact interface names, with the same spelling and highlighted: italics or bold, always the same. If the interface is in another language, use the name as it appears.
5. The visible result after important steps. «A confirmation window appears with the six-digit code.» It tells the person carrying out the steps that they are on the right track.
6. Explicit choices. When a decision is needed, say so: «If you use an iPhone, go to step 7; otherwise continue».
A before-and-after example
Typical version:
Go into the router settings and change the Wi-Fi password, remembering to save. Be careful that all devices will be disconnected.
Rewritten version:
- Let connected people know: at the end, all devices will have to reconnect with the new password.
- From a computer connected to the network, open the browser and type the router address shown on its label.
- Log in with the administration credentials.
- Open the Wireless section and then Security.
- In the Password field, enter the new password.
- Click Apply. The connection drops for a few seconds.
- Reconnect the computer to the network using the new password.
The second version is longer, but it can be carried out without doubts, and the warning comes before the action that has consequences.
Warnings in the right place
Warnings work only if they appear before the step they refer to and if they are rare. A procedure with a warning every three lines teaches people to ignore them. Distinguish at most two levels:
- Note: useful information, no risk.
- Caution: there is a risk of losing data, interrupting a service or having to start over.
Images: when they help
Screenshots help when the element to find is hard to describe or when the interface is crowded. They do have a cost, though: they age at the first program update. Use them for key steps, cropped to the useful part, with a box or an arrow on the element to click. The text must still be enough on its own, including for people who cannot see the images.
The decisive test
The most effective check is to have someone who does not know the procedure carry it out while you watch without intervening. Every time they hesitate, go back or ask something, you have found a point to rewrite. In my work this ten-minute test uncovers more problems than any proofreading.
In short
- Define who carries it out, the end result and the starting situation before writing.
- One action per step, verb first and context before the action.
- Use exact interface names and state the visible result after important steps.
- Warnings go before the risky action and should be few.
- Having another person carry out the procedure is the most reliable test.
