Why instructions are so hard to write

Everybody has followed a set of instructions that failed, and the usual reaction is that the writer was careless. Occasionally that is true. Far more often the writer knew the subject extremely well, and that is precisely what went wrong.

The difficulty has a name among people who study it: once you know something, you cannot reliably imagine not knowing it. An expert writing instructions has lost access to the state of the reader, and the steps that have become automatic are the ones that disappear from the page. The gap is rarely in the hard parts, which the writer remembers finding hard. It is in the small connecting actions that stopped being visible years ago.

This explains a pattern that otherwise looks strange, which is that instructions written by somebody who has just learned the task are often better than those written by the person who invented it. The recent learner still remembers where they got stuck. They also tend to write the step that nobody thinks worth writing, such as which way round a part goes, and that step is very often the one that defeats everybody else.

The remedy is not better writing but testing, and testing of a specific kind. Give the instructions to somebody who has never done the task, watch them without helping, and write down every point at which they hesitate. The hesitations are the document's faults, and the writer will not predict them. The hardest part of this method is the watching without helping, because the instinct to explain is overwhelming and explaining destroys the measurement.

There is one more rule that applies everywhere and is almost always broken. Say what the reader should see after each step. An instruction that only says what to do leaves somebody who has gone wrong with no way of discovering it until much later, when the error is expensive to undo. The sentence that prevents this costs seven words and is left out because it feels obvious to the person who already knows what it should look like.