---
name: writing-tutorials
description: Writes step-by-step tutorials and how-to guides where every step has a verifiable checkpoint, full commands, and expected output. Use when the user asks to write a tutorial, a how-to guide, a getting-started guide, a walkthrough, or onboarding steps for learners. Do not use for reference documentation, conceptual overviews and READMEs, or API endpoint docs — separate skills cover those.
---

<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Writing Tutorials

## When to use / when NOT to use
- **Use for:** tutorials, how-to guides, getting-started walkthroughs, workshop material — content a learner follows top to bottom.
- **Do NOT use for:** reference docs (writing-api-documentation), conceptual overviews/READMEs (writing-technical-documentation), or blog posts (writing-blog-posts).

## House rules

1. **State the destination upfront:** end result, prerequisites (with versions), and honest time estimate — before step 1.
   - ✅ "By the end you'll have a deployed webhook receiver. Prerequisites: Python 3.12, an ngrok account. Time: ~20 minutes."
   - ❌ Diving into `mkdir project` with no destination stated.

2. **One path only.** No forks, options, or "alternatively…" mid-tutorial; link alternatives at the end.
   - ✅ "We'll use SQLite. (Using Postgres instead? See the appendix link at the end.)"
   - ❌ "You can use SQLite, Postgres, or MySQL here — configure accordingly."

3. **Every step ends with a verifiable checkpoint.**
   - ✅ "Run `curl localhost:8000/health` — you should see `{"status":"ok"}`."
   - ❌ Three file edits in a row with no way to know they worked.

4. **Full commands, full expected output.** Never `cd <your-project>`; never truncate output the learner must compare against.
   - ✅ The exact command plus the exact lines it prints.
   - ❌ "Run the usual migration commands."

5. **Never skip steps that "everyone knows."** Activating the virtualenv, exporting the variable, saving the file — write them.
   - ✅ "Save the file, then in the same terminal run…"
   - ❌ "Simply configure your environment."

6. **Troubleshoot the 3 most likely failures inline**, at the step where they occur — not in a distant appendix.
   - ✅ "If you see `Address already in use`, another process holds port 8000: run `lsof -i :8000`…"
   - ❌ A generic "Troubleshooting" section listing every possible error.

7. **End with "what you built + where to go next":** recap the result and give 2–3 concrete next links.

## Workflow

1. Do the task yourself start to finish; record every command, output, and mistake you hit (mistakes become inline troubleshooting).
2. Write the header: end result, prerequisites with versions, time estimate.
3. Convert your recording into numbered steps, each with command → expected output → checkpoint.
4. Add inline troubleshooting for the 3 most likely failures at the exact steps they occur.
5. Validate: replay the tutorial verbatim in a clean environment (fresh directory/venv/container); any deviation between the doc and reality is a bug — fix it and replay until it runs clean.

## Edge cases
- **Can't provide a clean environment for replay** → state the tested environment explicitly ("Tested on macOS 15, Python 3.12.4") and flag untested paths.
- **Long tutorial (over ~15 steps)** → split into parts, each part ending at a working state a learner can stop at.
- **Steps involving paid/external services** → say the cost and offer the free-tier route as the single main path.

## References
Extended before/after examples: see [references/examples.md](references/examples.md).