Tutorial writing

Writing step-by-step tutorials

Craft guidance for the "how to connect/configure/set up X" genre. The goal: a reader who follows top-to-bottom and succeeds on the first try — no backtracking, guessing, or hitting a wall the draft didn't warn about.

The non-negotiables

1. The real UI is ground truth — mirror it exactly. Use the actual field labels, button text, and option wording the reader sees ("App acts on behalf of a user," not "user mode"). Document fields in the order the form presents them. If a screenshot contradicts the draft, the draft is wrong — fix it to match, don't argue from docs.
2. Front-load values the reader reuses later. If Step 5 reuses a port/name/ID chosen in Step 1, state the concrete value in Step 1 and reuse it verbatim downstream. No scroll-up "what did I pick?" or scroll-down "what's this for?" dance.
3. Order steps by real dependency, not by topic. Watch for chicken-and-egg traps — a required field that blocks Save but whose value only appears in a later step. Pull the prerequisite earlier. Walk the flow as the reader: can each step be completed with only what they have so far?
4. Never write "the docs," "the UI," or "the settings" without a link or exact label. Link the specific page (deep-link if you can) or name the exact menu path (Access Management → Connected Apps → Create app).
5. Every transition before an action must state the action. "Now add it." before a code block leaves the reader guessing how. Say the verb: "Run the command below, filling in your Client ID and Secret." A code block is not self-explanatory.
6. Show the expected output after a command, genericized. The success message ("Added HTTP MCP server … to local config") tells the reader it worked. Replace machine-specific paths/IDs with placeholders (/Users/<you>/.claude.json, /path/to/your/project) so it reads as a template.
7. Close each phase with a "verify it worked" checkpoint. After a setup step give a way to confirm success (tool --version, a status badge, a list command that returns rows) before moving on — so failures surface where they happened, not three steps later.
8. Account for client/GUI variants of the same step. The same action looks different across surfaces (a terminal list vs. a VS Code panel; CLI output vs. a ⚠ Needs Auth → ✓ Connected badge). Add a short "Using the X? You'll see …" note so the GUI user isn't lost.

Accuracy discipline (the reputation rule)

Readers run your commands and notice when something's wrong — so does the team that owns the product.

• Ground every product specific in a live source at write time — tool names, scopes, endpoints, plan/pricing, UI labels, versions. These drift silently. Fetch the live doc (.md page if it has one); cite the human page.
• Use canonical product names, and write them in full on every mention — check the current name before shipping (products get renamed). Don't drop a qualifier ("the Platform," "the Builder") that makes it ambiguous.
• Link a product mention to the right destination: the product console when the intent is "log in and do this," a docs page when it's "go read more." Don't point a "open the product" mention at docs.
• Re-verify on pushback. If the user or a reviewer questions a fact — even one you stated confidently — fetch again before defending it. Confident-but-stale is the cardinal sin.
• Trace troubleshooting to the authoritative source, not a plausible story. A symptom can have a misleading surface message (an "OAuth state mismatch" that's really an upstream invalid_scope; a "JSON parse error" that's really a bare 401). And a verification command can itself false-positive (a masked/empty value printing "present," a && chaining off the wrong command) — confirm the check measured what you think.

Structure that works

• Title: outcome-oriented — "How to Connect X to Y," not "X Overview."
• One-line promise up top: what they'll be able to do by the end, concretely.
• "What you'll need": prerequisites as a checklist (accounts, installs, permissions, paid-plan requirements) — with the check for each (tool --version).
• Disambiguation callout when two similarly-named things exist — state plainly which one this guide is about and how to tell them apart.
• Numbered steps grouped into a few labeled phases (Create → Connect → Verify → Use).
• Reference tables (scopes, endpoints, regions) pulled out of the prose so steps stay scannable and the table updates independently.
• "Why this matters" close (the durable point), an FAQ for predictable follow-ups (does it cost money, is it the same as <other client>, why did a tool fail silently), and a "things change" footer pointing at the canonical doc.

Permissions / scopes tables

• Lead with the scope/role, then "what it unlocks," then the specific actions. One scope → many capabilities, so scope-first avoids repeating it across task rows.
• Note hierarchy ("Admin includes Viewer") so a reader who only sees the broader role isn't blocked.
• Call out state-changing scopes explicitly ("grant deliberately"), and flag scopes from a different family the main set won't cover.
• Use the human-readable picker label in instructions (raw scope string parenthetically).
• Make silent defaults loud. When a command applies a non-obvious default (e.g. registering at local/this-project-only scope), say so, point at the proof in the output, and give the exact flag to change it. Don't bury it as an aside.

Markdown / CMS gotchas

• For ordered lists that survive an interrupting comment/admonition, use 1. for every item and let Markdown auto-number — a literal 2./3. after an HTML comment often resets the count.
• Prefer fenced blocks for anything typed; show one copy-pasteable command, then explain its flags in a bullet list beneath it.

Revision workflow

1. Make the smallest edit that satisfies the ask; don't rewrite surrounding prose.
2. After editing one step, scan downstream for now-stale references (a renumbered step, a "three scopes" line that's now four, a "we'll do this in Step 2" that moved). Fix them in the same turn.
3. If the change alters a product fact, re-fetch the live doc before saving.
4. Surface an inconsistency you spot and offer to fix — don't silently leave it or change unrelated things.