Writing Instructions Someone Can Follow

Instructions are among the hardest things to write and among the least revised. The failures are consistent enough to be predicted before testing.

The writer knows too much

Someone who can perform a task has forgotten which parts required learning, and the steps that became automatic are exactly the ones omitted.

These gaps are invisible from inside. The instructions read as complete to their author and stop working at the first missing step for everyone else.

This is why watching someone follow them is worth more than any amount of rereading, and why it is so rarely done.

Sequence must match the action

Instructions have to be ordered the way the task is performed, including preparation that would otherwise be discovered too late.

A step requiring something not yet mentioned forces the reader to stop mid-task, and recovering from that is where most errors occur.

Listing what is needed before the steps begin solves most of this, which is why recipes are structured the way they are.

One action per step

Steps containing several actions are hard to track, since a reader who returns to the page cannot tell how far through the step they had reached.

Splitting them costs a little length and removes a common failure, particularly for tasks performed with hands occupied.

Numbering matters for the same reason. It gives the reader a place to return to, which prose instructions do not.

Say what success looks like

A reader needs to know whether a step worked before proceeding, and instructions frequently omit this entirely.

Describing the expected result converts a sequence of actions into something the reader can verify, and it catches errors at the point they occur.

It also helps with the common case where something goes wrong, since a reader who knows what should have happened can describe the problem accurately.

Warnings belong before the step

A caution printed after the action it applies to is useless, and this arrangement is surprisingly common in documents written by people who know the task.

Anything irreversible needs flagging in advance and in a way that survives skimming, since instructions are skimmed by almost everyone.

The same applies to points of no return more generally. Readers accept a warning that arrives in time and resent one that arrives afterwards.

Placement beats prominence here. A modest caution in the right position is followed far more often than an emphatic one printed in a block that readers have learned to skip.