Tutorial Writing

Tutorial Writing

Core Workflow

1. Identify the learner, starting point, outcome, prerequisites, and time budget.
2. Choose one concrete task and avoid turning the tutorial into a full reference manual.
3. Write steps that explain what to do, why it matters, and how to verify the result.
4. Include expected output, common failure points, and recovery notes where useful.
5. Link to reference docs for deeper details instead of overloading the path.
6. End with a finished artifact, working state, or next practical task.

Safety Rules

• Do not include unverified commands or screenshots as proof.
• Do not ask users to paste secrets into examples.
• Do not hide destructive or cost-incurring steps inside a tutorial.

Deliverable Shape

For tutorials, provide:

• Goal and audience
• Prerequisites
• Starting state
• Step-by-step walkthrough
• Expected result
• Verification checks
• Troubleshooting notes
• Next task

References

• Read references/tutorial-writing-checklist.md when writing or reviewing a tutorial or quickstart.