Writing instructions that survive real play

A guide fails when it assumes the reader is reading in order. Most readers arrive mid-page from a search, which changes how the structure has to work.

Quick answer

• Put the first executable step in the first screen of text.
• Give each section a heading that states the action.
• Repeat the prerequisite in every section that depends on it.

Why this keeps happening

Readers search for the step they are stuck on, not for the introduction. A guide organised as a narrative forces them to reconstruct context that could have been repeated.

The second failure is implicit knowledge. Steps that the author performs automatically are exactly the ones a beginner cannot follow, and they are the hardest to notice while writing.

What to do, in order

1. Put the first executable step in the first screen of text.
2. Give each section a heading that states the action, not the topic.
3. Repeat the prerequisite in every section that depends on it.
4. Number the steps and keep one action per step.
5. Add a short note for the most common failure at each step.
6. Test by watching someone follow it without your help.

How to measure it

Time to first success for a reader is the measure. If it takes more than ten minutes to reach a working result, the beginning is doing too much explaining.

Mistakes that undo the work

• Starting with three paragraphs of context.
• Combining two actions into one step.
• Assuming the reader has the same version as the author.

Frequently asked

Read next

• Writing Critique a Developer Can Read Without Defending
• The Invisible Tutorial: Why Good Games Don't Explain

Games worth trying

• 2244 Number Match
• BEEP OUT
• Bucket Sort 3D