# Examples — Tutorial House Style ## Contents - Complete worked example: tutorial opening + one step (bad → house style) - Checkpoint patterns - Inline troubleshooting pattern - Ending pattern - Gotchas ## Complete worked example **❌ Before:** ```markdown # Webhooks tutorial In this tutorial we will learn about webhooks. Webhooks are a way for services to notify each other. First, set up your environment and create a project. You can use Flask, FastAPI, or Django. Then write a handler for the webhook and test it works. ``` **✅ After (house style):** ```markdown # Receive Stripe webhooks locally By the end you'll have a local endpoint that verifies and logs Stripe events, reachable from the internet. **Prerequisites:** Python 3.12, a free Stripe test account, ngrok 3.x installed. **Time:** ~20 minutes. ## Step 1 — Create the project mkdir stripe-webhooks && cd stripe-webhooks python3 -m venv .venv source .venv/bin/activate pip install fastapi==0.115.0 uvicorn==0.30.0 stripe==10.5.0 Expected output ends with: Successfully installed fastapi-0.115.0 stripe-10.5.0 uvicorn-0.30.0 **Checkpoint:** `python -c "import fastapi, stripe; print('ok')"` prints `ok`. > If you see `command not found: python3`, install Python 3.12 from > python.org, then restart this step in a new terminal. ``` What changed: destination + prerequisites + time before step 1; one framework (no menu); full commands including venv activation; pinned versions; expected output; a checkpoint; the likeliest failure handled inline. ## Checkpoint patterns ✅ Observable and exact: - "You should see `{"status":"ok"}`." - "The dashboard now lists one endpoint with a green Active badge." - "`ls migrations/` shows one file ending in `_init.py`." ❌ Unverifiable: - "Make sure everything is configured correctly." - "The server should now be working." ## Inline troubleshooting pattern Place at the step, as a quote block, most-likely first: ```markdown > **`Address already in use`** — another process holds port 8000: > `lsof -i :8000`, stop it, rerun. > **`401 Unauthorized` from Stripe** — you exported the live key; > re-export the one starting with `sk_test_`. ``` Cap at 3 per step; more than that means the step itself needs splitting. ## Ending pattern ```markdown ## What you built A verified Stripe webhook receiver: signature checking, event logging, and a public URL via ngrok. ## Where to go next - Handle `invoice.paid` and update your database — see Persisting events - Deploy the receiver — see Deploying FastAPI - Full event catalog: Stripe docs, Webhook events ``` ## Gotchas - **The author's environment leaks in** (aliases, globally installed tools, exported variables from earlier work). Only a clean-environment replay catches these — do it, every time. - **Unpinned versions** make tutorials rot silently; pin every install and date-stamp the tested versions. - **"Simply", "just", "obviously"** mark exactly the places learners get stuck; delete the word, add the missing step. - **Screenshots of terminals** can't be copy-pasted or diffed; use text blocks for anything the learner must compare. - **Checkpoint drift:** when you edit a step, its expected output usually changes too — replay from the edited step onward, not just the step.