Writing Tutorials and How-To GuidesLesson 4.2

How to structure a developer tutorial step by step

tutorial introduction, prerequisite section, step structure, learning checkpoints, complete working outcome, tutorial scope, avoiding scope creep

Tutorial Structure

A tutorial must have a guaranteed working outcome. If the reader follows every step correctly and the result doesn't work, the tutorial is broken. Structure prevents this.

Required Tutorial Sections

Introduction — What you will build. One paragraph. Include a screenshot or output preview if possible.
Prerequisites — Everything the reader must have installed and know before starting. Be specific: versions matter.
Steps — Sequential. Each step has one action. Never combine two distinct actions in one step.
Checkpoints — After every 2–3 steps, include a verification command. Let readers confirm progress before continuing.
Working outcome — The final step produces a running, testable result.

Checkpoint Example

## Checkpoint: Verify the server is running

```bash
curl http://localhost:3000/health
```

Expected output:
```json
{ "status": "ok" }
```

If you see a connection error, check that you ran `npm start` in the correct directory.

Scope Discipline

Define your tutorial's scope in the introduction and defend it. Every scope expansion you add is another prerequisite you must explain. A tutorial that covers everything teaches nothing. Finish one thing completely before adding features.