Tutorial patterns for documentation - learning-oriented guides that teach through guided doing
This skill provides patterns for writing effective tutorials following the Diataxis framework. Tutorials are learning-oriented content where the reader learns by doing under the guidance of a teacher.
Target readers:
Tutorials are NOT:
Tutorials teach through action, not explanation. The reader should be doing something at every moment.
| Avoid | Prefer |
|---|---|
| "REST APIs use HTTP methods to..." | "Run this command to make your first API call:" |
| "Authentication is important because..." | "Add your API key to authenticate:" |
| "The dashboard contains several sections..." | "Click Create Project in the dashboard." |
After each action, tell readers exactly what they should see. This confirms success and builds confidence.
Run the development server:
```bash
npm run dev
You should see:
> Local: http://localhost:3000
> Ready in 500ms
Open http://localhost:3000 in your browser. You should see a welcome page with "Hello, World!" displayed.
### 3. One Clear Path, Minimize Choices
Tutorials should not offer alternatives. Pick one way and guide the reader through it completely.
| Avoid | Prefer |
|-------|--------|
| "You can use npm, yarn, or pnpm..." | "Install the dependencies:" |
| "There are several ways to configure..." | "Create a config file:" |
| "Optionally, you might want to..." | [Omit optional steps entirely] |
### 4. The Teacher Takes Responsibility
If the reader fails, the tutorial failed. Anticipate problems and prevent them. Never blame the reader.
```markdown
<Warning>
Make sure you're in the project directory before running this command.
If you see "command not found", return to Step 2 to verify the installation.
</Warning>
Repeating similar actions in slightly different contexts helps cement learning. Don't try to be efficient.
Use this structure for all tutorials:
---