# 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.

# 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.