# Tutorial Writing

> How to write step-by-step technical tutorials and setup/how-to guides a reader can follow top-to-bottom and succeed on the FIRST try — UI-fidelity, dependency-ordered steps, front-loaded values, scope/permission tables, "verify it worked" checkpoints, and the accuracy discipline that keeps commands from going stale. Use when writing or revising a hands-on numbered walkthrough, getting-started guide, or install/config how-to. For prose explainers see [[technical-content-structure]]; for SEO/frontmatter [[blog-seo-standards]].

- Skill: `prostdev/tutorial-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add prostdev/tutorial-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prostdev/tutorial-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: ProstDev (https://skillmd.com/u/prostdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/prostdev/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.