Tutorial Writing

Tutorial introductions must answer three questions: Who is this for? What will they build? How long will it take?

The three required elements:
1. Specific prerequisites — not "some programming experience" but "Node.js v18+, npm, basic JavaScript knowledge (functions, async/await)"
2. Specific outcome — "By the end, you'll have a working REST API that accepts JSON POST requests and returns paginated data"
3. Time estimate — "Takes about 45 minutes"

These elements help readers self-qualify: "Is this too easy? Too hard? Too long for right now?"

Without them, readers either:
• Abandon midway when they hit unfamiliar tools
• Skip a tutorial that would have been perfect for them

Key vocabulary:
• Prerequisites — skills, tools, and environment required before starting
• Expected outcome — the specific thing the reader will have built by the end
• Time estimate — approximate completion time to help readers plan
• Reader self-qualification — helping readers decide if the tutorial is the right level for them

Tutorial steps must be atomic, specific, and show both the action and the expected result.

The anatomy of a good tutorial step:
1. Imperative verb + specific action — "Add the following to your .env file:"
2. Code block — with the specific code to type
3. Expected result — "When you run npm run db:connect, you should see: Database connected ✓"
4. Brief explanation (optional but valuable) — "DATABASE_URL tells Prisma which database to connect to"

"Now configure your database connection" fails all four — it describes a goal, not an action. The reader is left wondering:
• What file do I edit?
• What do I type?
• How do I know if it worked?

Key vocabulary:
• Atomic step — a step that describes exactly one action with a clear success state
• Imperative instruction — steps written in command form: "Open", "Add", "Run", "Create"
• Expected result — the output or state change the reader should see after completing a step
• Code block — a formatted section showing exact commands or code to type

Tutorials must anticipate failure — the troubleshooting section is as important as the happy path.

Two types of error handling in tutorials:
1. Inline error handling — on steps most likely to fail:
"If you see 'ENOENT: no such file', check that you ran the previous step from the project root directory."

2. Troubleshooting section — at the end, listing the 3-5 most common errors:
"Error: connect ECONNREFUSED → Your PostgreSQL server isn't running. Run: brew services start postgresql"

Why Option A fails: forum deflection is lazy; it means the author hasn't done the work.
Why Option B is impossible: different OS, permissions, versions, and environments mean errors are inevitable.
Why Option D fails: tutorials must work across macOS, Linux, and Windows — testing on one OS is insufficient.

Key vocabulary:
• Happy path — the successful path through a tutorial where nothing goes wrong
• Troubleshooting section — a section at the end of a tutorial covering common failure scenarios
• Inline error handling — step-specific notes about likely errors and their solutions
• OS-specific note — a callout for steps that differ between Windows, macOS, and Linux

Long tutorials need checkpoints — intermediate verification moments that let readers confirm they're on track before proceeding.

Checkpoint structure:
1. State description — "At this point, you should have: a running server at localhost:3000, a connected database, and 3 API endpoints"
2. Verification method — "Run: curl localhost:3000/health. Expected output: {"status": "ok"}"
3. Recovery instruction — "If your health check fails, check step 12 — the PORT environment variable may not be set"

Checkpoints work like git commits — they give readers a known-good state to return to if something goes wrong.

Checkpoint frequency guidelines:
• Every 5-7 significant steps
• After any complex configuration
• Before significant build milestones

Key vocabulary:
• Checkpoint — an intermediate verification step in a tutorial confirming correct state before continuing
• Verification command — a command that readers run to confirm their setup is correct
• Known-good state — a confirmed, working point in a tutorial from which the reader can continue confidently
• Recovery path — instructions for how to get back to a known-good state after an error

Tutorial conclusions must consolidate learning and immediately provide the next learning challenge.

The four elements of a strong tutorial conclusion:
1. What was built — one-sentence summary of the outcome
2. What was learned — the key concepts or patterns (2-3 bullet points)
3. Next steps — 2-3 specific, progressively harder challenges:
• Easy: "Add authentication to the API" (with link)
• Medium: "Deploy to Railway with CI/CD" (with link)
• Advanced: "Add a rate limiter and caching layer"
4. Completed code — a link to the final repository

Option B (20+ links) creates decision paralysis — too many options = no action taken.

Key vocabulary:
• Learning consolidation — restating the key lesson after completion to reinforce retention
• Progressive next steps — follow-up challenges ordered by increase in difficulty
• Decision paralysis — choice overload that causes readers to take no action (too many links)
• Completed code repository — the final, working code as a reference solution