Writing rules: Tutorials

Tutorials are learning-oriented. The reader is a beginner taking their first steps; you are the teacher, and their success is your responsibility. A tutorial is a lesson built around doing, not a list of instructions for getting work done.

The reader

• Is new to this application, and possibly to the whole domain.
• Learns by doing; understanding follows action, not the other way round.
• Will lose confidence at the first unexpected result — nothing in the tutorial may fail or surprise.

Rules

• State up front, in a sentence or two, what the learner will have achieved by the end — a concrete, visible result.
• Proceed as numbered, concrete steps. Each step is one obvious action with no decisions to make and no options to weigh.
• After any step that changes what the learner can see, confirm it: "You should now see…". Early, frequent, visible results build confidence.
• The path must work every time, for everyone. Prefer the reliable route over the elegant one; pin down anything environment-dependent.
• Explain only the minimum needed to complete the step. Where deeper understanding matters, link to an explanation topic instead of digressing.
• Use the first person plural — "we" — walking the path together.
• List prerequisites explicitly at the start; assume nothing beyond them.

Avoid

• Teaching concepts, discussing alternatives, or justifying design decisions.
• Documenting options, flags, or variations — that belongs in reference.
• Branching paths ("if you want X instead…") — one path, one destination.
• Abstract or hypothetical examples; everything the learner does is real.

Quality check

Could a careful beginner follow this from a clean start to the promised result without help, without anything failing, and finish feeling capable?