A support inbox is the most honest editing tool ever invented. One Tuesday, a customer wrote in to say she had spent forty minutes trying to reset her password. The instructions said: "You can reset your password by clicking the link on the login page, and then entering your email address." She clicked. She entered her address. She waited.
The instructions never mentioned pressing the button labeled "Send reset link." The writer had built the feature and could not see the gap.
You know where the light switch is in your own house. A guest does not. When you write instructions for a task you have done a hundred times, your brain fills in the gaps automatically, and those gaps are exactly where a first-time reader stops. The work, then, is not "write clearly." It is to reconstruct the reader's ignorance on purpose.
One action per step
Count the verbs in a step. If there are two, you usually have two steps.
Weak: "Open the Settings menu and select Privacy, then turn off location sharing."
That is three actions wearing a single number. A reader who turns off location sharing in the wrong tab will blame herself. Numbered steps exist to be checkpoints, so each number should end somewhere the reader can verify.
Strong:
- Open the Settings menu.
- Select Privacy.
- Turn off Location Sharing.
The "and" is the tell. Scan your steps for "and," "then," and "after that." Not every one hides a step, but most do.
Say what to do, not what will happen
Instructions written in the indicative mood tell the reader about the task instead of directing it.
Weak: "The user will then click Save." Strong: "Click Save."
Weak: "Once you have navigated to the dashboard..." Strong: "Open the dashboard."
Yank every "you will" and "the user will." The imperative is shorter, it removes all doubt about who acts, and it reads as confident. One exception is worth keeping: when a result deserves its own line, give it one.
Click Save.
The file downloads to your Downloads folder.
The confirmation line tells the reader she did it right.
Conditions and warnings go first
Two ordering rules do more for followability than any amount of polish. Both come down to the same principle: the reader should know what she is getting into before she starts.
Conditions before actions
A condition placed after the action arrives too late. The reader has already begun, and now has to back up.
Weak: "Close the file, if it is open." Strong: "If the file is open, close it."
Conditions belong at the front, where the reader can decide whether to read on at all. The same applies to "when," "unless," and "before."
Warnings before the risk
A warning placed after the step it governs is a warning after the damage.
Weak: "Delete the old database. This cannot be undone." Strong: "Deleting the database cannot be undone. Delete the old database."
This is not about drama; it is about sequence. The reader's eye reaches the instruction, acts, and only then reads the part about consequences.
Match the screen, then cut the cushioning
Two habits matter equally here: how you name things, and how much padding surrounds them.
Name things exactly as they appear
If the button says "Sign in," your instructions say "Sign in." Not "log in," not "sign-in," not "signin."
It is the cheapest fix available, and the one most often skipped, because the writer works on the product and never thinks to copy the labels. Where you can, quote the label exactly: click Sign in. Capitalization carries information too: if "Account" is capitalized in the menu while "account" is a general noun, the reader learns the difference without you explaining it.
Cut the hedges
| Weak step | Stronger rewrite | What changed |
|---|---|---|
| "You may want to save your work first." | "Save your work first." | Removed a hedge that made a required step sound optional |
| "Simply enter your username and password." | "Enter your username and password." | "Simply" implies ease, and insults the reader who is stuck |
| "Please try clicking Refresh." | "Click Refresh." | "Try" tells the reader the writer is not sure the fix works |
| "In order to export the file, you will need to..." | "To export the file..." | Five words doing no work |
| "It should be noted that settings reset on logout." | "Settings reset on logout." | Removed the throat-clearing |
Look at the third row again. "Try" is a hedge with a cost: it signals uncertainty, and the reader who clicks Refresh and sees nothing change now distrusts the instructions themselves. Cutting filler words is the same discipline at sentence level, and it pays off fastest in procedures, where every wasted word is read under stress.
Separate steps from reference
A procedure is a sequence. Reference material is a lookup table. Mixing them makes both harder to use. If your instructions include a long list of fields and what each one does, move that list to the end of the section and leave a pointer: "For field descriptions, see the table at the bottom of this page."
Readers follow a procedure once and consult reference many times. Interleaving them forces every reader to carry context she does not need. Run the reference list through a readability checker separately from the steps, since the two have different jobs and different standards.
Test it by watching, not rereading
The only reliable test is a person who has never done the task, doing it while you watch and say nothing.
Sit on your hands. When she pauses, note the step number. When she asks a question, write it down instead of answering. Each pause is your revision list, and answering repairs the session while destroying the evidence.
If you cannot find a person, read the steps backward, from last to first. Reversing the order breaks the momentum that lets your brain fill gaps. When even that is impractical, use length as a proxy: steps that run past twenty-five words are usually two steps, and a sentence counter will list them faster than reading will.
Frequently Asked Questions
Should I number the steps?
Yes, for procedures. Numbers give the reader a place to return to after an interruption, and they make support conversations possible. "I'm stuck on step 6" saves everyone time. Use bullets only for unordered lists of options.
How many steps can one set of instructions have?
As many as the task needs, but break long sets into labeled sections. A forty-step task split into four sections of ten works far better than forty items in one undifferentiated list.
What about screenshots?
Useful for orientation, dangerous as a substitute for words. A screenshot cannot be searched, cannot be read by a screen reader, and goes stale the moment the interface changes. Pair it with the step text.
Is a video better than written instructions?
Better for spatial tasks like assembling furniture, worse for anything a reader needs to look up. Video cannot be skimmed, and a reader who needs step 9 has to scrub to find it. For software, write the instructions down.
How do I handle steps that apply only to some readers?
Put the condition first, then indent the conditional steps beneath it: "If you use two-factor authentication: 1. Open your authenticator app..." Readers without that condition skip the whole block instead of reading four steps that turn out not to apply.
Fix the step she stumbled on
Find one person who has never done the task, and watch her do it once. Every pause she makes without asking a question is a step you should rewrite. There are usually fewer than five. Fix those five and you have fixed the procedure.