Developer Docs Playbook

Repo-level documents readers meet inside the repository rather than on a docs site. Each maps onto the Diátaxis quadrants — knowing the blend tells you what belongs and what to evict.

README

Blend: landing page — pitch (one breath) + mini-tutorial (quickstart) + link hub. The README's job is routing: in 60 seconds the reader knows what this is, whether they want it, and where to go next.

# project-name

<One sentence: what it is and who it's for. No adjectives that a competitor
couldn't also claim.>

<Optional: badges row. Optional: one screenshot/GIF if visual.>

## Why

<2–4 sentences or bullets: the problem and the angle. Honest, concrete.>

## Quickstart

<The shortest real path to a working result — install, minimal use, expected
output. 5 minutes max. This is a micro-tutorial: one path, no choices, verified
by actually running it.>

## Documentation

<Links into the docs site / docs folder, organized by quadrant if there are
enough: Tutorial · How-to guides · Reference · Concepts.>

## Contributing / License

<One line each, linking to CONTRIBUTING.md and LICENSE.>

Rules:

• Under ~300 lines. A README hoarding full API tables, six tutorials, and an FAQ is a docs site in denial — split and link.
• Quickstart must be executed before shipping, exactly like a tutorial step.
• First sentence carries the page. "A fast, flexible toolkit" says nothing; "Convert OpenAPI specs into typed fetch clients" says everything.
• For a monorepo package, the README is shorter still: what it is, install, one example, link to the root docs.

CONTRIBUTING

Blend: how-to guide(s) for the contributor audience. Assume a competent developer who has never seen this repo.

Cover, in order of contributor need:

1. Dev setup — clone → install → run tests, with the real commands and the real expected output. Note required versions and any secrets/services needed.
2. Day-to-day loop — run, test, lint, typecheck commands; where the code lives; naming/branch conventions actually enforced.
3. Submitting — PR expectations, review process, commit format if enforced (link the linter config rather than restating it).
4. What maintainers want / don't want — issue triage labels, good-first areas, features that will be declined (saves everyone a dead PR).

Rules: verify every command; document the enforced reality, not the aspirational process; if CI is the source of truth, link the workflow file.

ARCHITECTURE

Blend: explanation, with a reference skeleton (the component inventory). Audience: a contributor about to make their first non-trivial change. Matklad's test applies: the doc should tell them where things are and what crosses what, so they can navigate without reading everything.

Structure: bird's-eye view (one paragraph + one diagram) → codemap (top-level directories/modules, one line each, why it exists not just what it contains) → cross-cutting concerns (boundaries, invariants, layering rules that code review enforces) → key design decisions with links to ADRs.

Rules: stay at the architecture altitude — no function-level detail that rots in a week; name the invariants ("nothing in core/ imports from adapters/"); update triggers are structural changes, so keep it short enough that updating is plausible.

ADR (Architecture Decision Record)

Blend: explanation, decision-shaped, immutable once accepted — new decisions get new ADRs that supersede old ones; history is the point.

# ADR-NNNN: <Decision as a verb phrase: "Use Postgres for the job queue">

- **Status:** Proposed | Accepted | Superseded by ADR-MMMM
- **Date:** YYYY-MM-DD

## Context
<The forces: requirements, constraints, what hurts today. Facts, not advocacy.>

## Decision
<What we will do, stated in full sentences, active voice: "We will...">

## Consequences
<What becomes easier, what becomes harder, what we are betting on. Include the
negative consequences — an ADR with no downsides recorded is a sales document.>

## Alternatives considered
<Each rejected option with the honest reason it lost.>

Number sequentially in docs/adr/ (or the project's existing location — detect before inventing). Never edit an accepted ADR's decision; append status changes.

CHANGELOG

Blend: pure reference, reverse-chronological. Follow Keep a Changelog unless the project already does otherwise (detect: existing format wins).

## [Unreleased]

## [2.1.0] - 2026-06-10
### Added
### Changed
### Deprecated
### Removed
### Fixed
### Security

Rules: entries describe observable change for the user of the package, not internal refactors ("Fixed crash when config file is empty", not "refactored ConfigLoader"); breaking changes marked loudly and listed first under Changed/ Removed; if the repo generates the changelog from commits, fix the commits or the generator config — do not hand-edit generated output.

Runbook

Blend: how-to guide under stress. The reader is on call, paged, possibly at 3am, possibly not the service owner. Optimize for a degraded reader.

# Runbook: <symptom or alert name, matching the alert text exactly>

**Severity guide:** <when this is urgent vs can wait until morning>
**Dashboard:** <link> · **Logs:** <query link or exact command>

## Confirm
<1–3 checks that distinguish this failure from look-alikes. Copy-pasteable.>

## Mitigate
<Numbered, imperative, copy-pasteable commands. State the blast radius of each
action BEFORE the command. Safest-first ordering.>

## Escalate
<When to stop self-serving and who to wake, with the actual channel/rotation.>

## Root-cause follow-up
<What to capture for the postmortem while evidence is fresh.>

Rules: every command literal and copy-pasteable (no <your-cluster> placeholders where the real value is knowable); destructive mitigations flagged before the command with reversibility stated; test runbooks the way you test tutorials — stale runbooks fail at the worst possible moment.

API reference (hand-written portions)

Full treatment in reference.md. Repo-specific note: prefer generating from docstrings/OpenAPI/typedoc when the toolchain exists, and spend hand-written effort on the prose around the generated core — overview per module, conceptual grouping, "start here" pointers.

Docs Stacks

Per-stack conventions: detection, frontmatter, nav registration, and component vocabulary. Golden rule: detect, then conform. Read 2–3 existing pages in the repo before writing one — the project's actual usage beats this file. Never mix stacks' syntaxes; each admonition/tab/step syntax below is valid only in its stack.

Universal quadrant-to-component mapping (translate per stack):

Fumadocs

Detect: source.config.ts, or fumadocs-ui/fumadocs-mdx in package.json. Content: .mdx, usually content/docs/. Nav: meta.json per folder ({ "title": ..., "pages": [...] }) — new pages must be added there if pages is explicit.

Frontmatter: title and description required.

Global components (no import): <Callout type="info|warn|error" title="...">, <Cards>/<Card title href>, <Steps>/<Step>, code blocks with title="file.ts" and {1-3} line highlighting.

Imported components:

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Files, File, Folder } from 'fumadocs-ui/components/files';
import { TypeTable } from 'fumadocs-ui/components/type-table';

• <Tabs items={['npm','pnpm']} groupId="pkg" persist> — groupId+persist carries the choice across pages.
• <TypeTable type={{ field: { description, type, default, required } }}/> — prefer over markdown tables for props/config.
• <Files>/<Folder name defaultOpen>/<File name> for directory trees.

Docusaurus

Detect: docusaurus.config.js|ts. Content: docs/, .md/.mdx. Nav: sidebars.js|ts; with autogenerated sidebars use sidebar_position frontmatter instead.

Frontmatter: title, description; optionally id, slug, sidebar_position, sidebar_label.

Admonitions (Markdown-native, no import):

:::note
:::tip
:::info
:::warning
:::danger Custom Title
content
:::

Tabs require imports:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="package-manager">
  <TabItem value="npm" label="npm">...</TabItem>
  <TabItem value="pnpm" label="pnpm">...</TabItem>
</Tabs>

Code blocks: ```ts title="config.ts" {2-3} showLineNumbers. Use // highlight-next-line comments as an alternative. No built-in steps component — numbered headings or ordered lists.

Starlight (Astro)

Detect: @astrojs/starlight in astro.config.* / package.json. Content: src/content/docs/, .md/.mdx. Nav: sidebar config in astro.config.*; autogenerated groups pick up new files automatically.

Frontmatter: title required; description strongly expected.

Components from one package:

import { Tabs, TabItem, Steps, Card, CardGrid, Aside, FileTree, Badge, LinkCard } from '@astrojs/starlight/components';

• Asides have Markdown syntax too (preferred for plain callouts):

:::note
:::tip
:::caution
:::danger
content
:::

• <Steps> wraps a single ordered list (not per-step children):

<Steps>
1. Install the package.
2. Run the dev server.
</Steps>

• <Tabs syncKey="pkg"> syncs tab choice across pages.
• <FileTree> wraps an unordered list of paths.

MkDocs (Material)

Detect: mkdocs.yml. Content: docs/, .md only — no JSX/MDX, ever. Nav: explicit nav: in mkdocs.yml if present — new pages must be added; without nav:, file structure is the nav.

Frontmatter: optional title, description.

Admonitions (4-space indented content; Material theme):

!!! note "Optional title"
    Indented content.

!!! warning
??? info "Collapsible (closed)"
???+ tip "Collapsible (open)"

Tabs (requires pymdownx.tabbed extension — check mkdocs.yml before using):

=== "npm"

    ```bash
    npm install pkg
    ```

=== "pnpm"

    ```bash
    pnpm add pkg
    ```

Code blocks: ```py title="app.py" hl_lines="2 3". Check which pymdownx extensions are enabled before using their syntax — unrendered admonition syntax in production is the classic MkDocs failure.

VitePress

Detect: .vitepress/config.*. Content: repo root or docs/, .md with Vue available. Nav: themeConfig.sidebar in .vitepress/config.* — new pages must be added.

Frontmatter: title, description; layout options like outline.

Containers:

::: info
::: tip Custom Title
::: warning
::: danger
::: details Click to expand
content
:::

Code features: ```ts [config.ts] for filename, {2,4-5} highlighting, // [!code highlight], // [!code focus], // [!code ++]/// [!code --] comment directives. Code groups for variants:

::: code-group

```bash [npm]
npm install pkg

pnpm add pkg

:::

## Mintlify

**Detect:** `docs.json` (current) or `mint.json` (legacy). **Content:** `.mdx`.
**Nav:** `navigation` array in `docs.json` — every page must be listed or it is
invisible.

Frontmatter: `title`, `description`; optionally `icon`, `sidebarTitle`.

Built-in components (no imports):

```mdx
<Note> <Tip> <Warning> <Info> <Check>

<Steps>
  <Step title="Install">...</Step>
</Steps>

<Tabs>
  <Tab title="npm">...</Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="FAQ item">...</Accordion>
</AccordionGroup>

<CodeGroup>  <!-- multiple fenced blocks inside, filename as block title -->

<ParamField path="name" type="string" required>...</ParamField>
<ResponseField name="id" type="string">...</ResponseField>

ParamField/ResponseField are the reference-quadrant workhorses; prefer them over tables for API docs. OpenAPI pages can be generated from a spec referenced in docs.json — prefer that over hand-writing endpoint pages.

Plain Markdown (no stack)

Detect: none of the above markers. READMEs, docs/ folders rendered on GitHub/GitLab.

• GitHub-flavored Markdown only: tables, task lists, <details><summary> for collapsibles.
• GitHub alerts work in READMEs and rendered .md:

> [!NOTE]
> [!TIP]
> [!IMPORTANT]
> [!WARNING]
> [!CAUTION]

• No tabs component exists — present one recommended path, with alternatives as separate subsections.
• Mermaid fences render on GitHub: ```mermaid.
• Relative links between docs files so they work both on GitHub and in clones.

Explanation Playbook

Explanation is a discussion: understanding-oriented, theoretical. The reader is studying, away from the keyboard — maybe evaluating the project, maybe trying to build a mental model after weeks of cargo-culting the how-tos. Your job is to illuminate: context, reasons, connections, trade-offs.

Explanation is judged by one metric: does the reader understand the topic more deeply, and can they now reason about cases the docs never covered?

The contract with the thinker

• No instructions. The moment numbered steps appear, the page has changed quadrant. Describe that something is done and why; link to the how-to for how.
• Perspective is allowed — and must be honest. Unlike reference, explanation may have an opinion ("we chose eventual consistency because..."), but it must admit alternatives and costs. An explanation that reads like advocacy teaches nothing.
• Bounded topic. "About the scheduler" is a topic; "About the project" is a landfill. One concept, its context, its connections.
• Readable away from the machine. No prerequisites to execute anything. A good explanation works printed on paper.

Structure template

# <Topic> — but phrased as the question it answers when possible
# e.g. "Why deploys are immutable" / "How the scheduler decides what runs next"

<Opening: the question this page answers and who tends to ask it.>

## The problem / the context

<What situation makes this topic matter. What was true before, what forces apply.>

## How it works / the design

<The mental model. Diagrams welcome. Connect to things the reader already knows;
analogies allowed if honest about where they break.>

## Why this design

<The reasons. The constraints that drove it. What was optimized for.>

## Trade-offs and alternatives

<What this design costs. What the rejected alternatives would have given and
taken. When a different choice would be right.>

## Where this shows up

<Links: the reference entries that embody this, the how-tos it makes sensible.>

Adapt freely — explanation is the quadrant where structure may serve the argument. The template is a default, not a form.

Writing rules

1. Lead with the question. The best explanation titles are questions readers actually ask: "Why is there a build step?", "What counts as a breaking change?"
2. Build from the known to the unknown. Anchor each new idea to one already established — in this page or in a linked one.
3. Make the forces visible. Designs are responses to constraints. Name the constraints (performance, compatibility, team size, history) and the design becomes derivable instead of memorizable.
4. Honest about history. "This API is shaped this way because it predates X" is more useful than a retconned justification.
5. Analogies declare their limits. "Topics are like folders, except a message can be in many topics" — the except clause is the valuable part.
6. Diagrams for structure, prose for causality. A boxes-and-arrows diagram shows what connects to what; the text must still say why.
7. No duplicate facts. Specific signatures, defaults, limits belong in reference — link, don't restate, or the copies will diverge.
8. It may be long, never meandering. Each section advances the reader's model. If a section could be deleted without weakening understanding, delete it.

Where explanation pages come from

The highest-value explanation topics surface as repeated friction:

• A question asked in three issues/discussions → it wants a page.
• A how-to that keeps growing "background" sections → extract the background.
• A design decision that surprises every new contributor → explain the forces.
• An ADR that users (not just maintainers) keep getting linked to → write the public-facing explanation it is standing in for.

Common defects when improving an existing explanation

• Steps smuggled in — a "for example, run..." sequence that became a de facto how-to. Extract to a guide, link back.
• Advocacy without costs — reads like a launch post. Add the trade-offs section; credibility lives there.
• Unbounded scope — "Architecture" pages covering nine subsystems at one paragraph each. Split into per-concept pages with a short map page on top.
• Reference duplication — tables of options with commentary. Keep the commentary, link the tables.
• Staleness of rationale — "we do X because Y" where Y stopped being true two majors ago. Verify claims about the present against the current code; move superseded reasoning into an explicit history note.

How-to Guide Playbook

A how-to guide is a recipe: goal-oriented, practical. The reader is a competent user in the middle of real work with a specific problem. They are not here to learn your project — they are here to get something done and leave.

The how-to is judged by one metric: does it get the reader from their situation to their goal with no wasted motion?

The contract with the worker

• Assume competence. The reader can install software, read code, and use a terminal. Do not re-teach basics the tutorial covered — link to it for newcomers.
• Start from the task, not the tool. The title and framing match what the reader is trying to do ("Rotate API keys without downtime"), not the feature that happens to be involved ("Using the KeyManager class").
• Steps, not lessons. Action sequence with minimal connective tissue. The reader will adapt your recipe to their context — write it so adaptation is easy.
• Real-world shaped. How-tos may address messy realities tutorials avoid: existing data, production constraints, partial migrations.

Structure template

# How to <accomplish specific goal>

<One sentence: when you'd need this. One sentence: what the approach is.>

## Prerequisites

- <state the reader must already be in — versions, access, prior setup>

## Steps

### 1. <Action>

<Instruction. Code/command.>

### 2. <Action>

...

## Verify it worked

<How the reader confirms success — a command and its expected signal.>

## Troubleshooting        <!-- only if there are known, common failures -->

**<Symptom>** — <cause>. <Fix.>

## Related

- <link to reference for the options used>
- <link to explanation for the concept involved>

Writing rules

1. Title starts with "How to" + a verb + the user's goal. If you cannot name the goal concretely, you do not have a how-to topic yet.
2. "You" voice, imperative mood. "Set maxRetries to 0", not "the user should consider setting...".
3. Prerequisites are a checklist of state, not a story. Each one verifiable.
4. One reliable path through the task. Where genuinely different contexts need different steps (npm vs pnpm, staging vs prod), use the stack's tabs component — never inline "if/otherwise" prose forks.
5. Every step earns its place. If a step is optional, either cut it or mark it (optional) with the condition that makes it needed.
6. Always end with verification. A recipe without "how do I know it worked" is half a recipe.
7. Link instead of explaining. One clause of "why" is fine when it prevents misuse; three sentences of why is an explanation page leaking in.
8. Flag destructive steps before them, with the stack's warning callout: what is destroyed, whether it is reversible, how to back up.

Scoping: one guide or several?

A how-to covers one goal. Signals you have accidentally scoped two guides:

• The title contains "and" joining two outcomes.
• Steps 1–5 and steps 6–11 could each be followed alone usefully.
• You need two different "Verify it worked" sections.

Split them and cross-link. Conversely, do not shred one goal into three stub pages — a guide shorter than its own boilerplate should be folded into a sibling.

What does NOT belong in a how-to

Common defects when improving an existing how-to

• Tutorial cosplay — opens with "What is X?" and installs from scratch. Delete the lesson; demand prerequisites instead.
• Feature-shaped, not task-shaped — "Using webhooks" tells the reader nothing about whether their problem is in here. Re-title around the goal and reorganize.
• No verification step — add one; it is the single highest-value fix.
• Drift — steps reference UI labels, flags, or file paths that have since changed. Verify every name against the current code.
• Choice paralysis — three alternative approaches presented equally. Recommend one, state when the alternatives win, or split the guides.

Reference Playbook

Reference is a dictionary: information-oriented, theoretical. The reader is working and needs a fact — a signature, a default, a constraint — fast. They will land mid-page from search, grab the fact, and leave.

Reference is judged by one metric: is it complete, correct, and findable? Trust is the product. One wrong default and the reader stops believing the page.

The contract with the looker-upper

• Describe, never instruct or advise. "Returns the user object or null" — not "you should check for null" (that's a how-to) and not "this elegant API..." (that's marketing).
• Be complete. Every public option, parameter, error code, and field — no "and other minor options". Omissions read as nonexistence.
• Mirror the code's structure. Organize by module/command/endpoint exactly as the machinery is organized, so location in docs predicts location in code. Do not organize reference by use case — that's how-to territory.
• Be boringly consistent. Identical section shapes for every entry. The reader learns the pattern once and navigates by it.

Entry templates

Function / method

### `functionName(param1, param2?)`

<One-sentence factual description of what it does.>

| Parameter | Type | Default | Description |
|---|---|---|---|
| `param1` | `string` | — (required) | <what it is, constraints> |
| `param2` | `number` | `100` | <what it is, valid range> |

**Returns:** `Promise<Result>` — <shape of the result>.

**Throws:** `ConfigError` when <condition>.

​```ts
const result = await functionName("orders", 50);
​```

CLI command

### `tool deploy [target]`

<One-sentence description.>

| Flag | Default | Description |
|---|---|---|
| `--env <name>` | `production` | <effect> |
| `--dry-run` | `false` | <effect> |

**Exit codes:** `0` success · `1` <condition> · `2` <condition>

Config option

### `server.maxConnections`

- **Type:** `number`
- **Default:** `512`
- **Constraints:** 1–65535
- **Since:** v2.3

<What it controls, stated factually. Interactions with other options if any.>

HTTP endpoint

### `POST /v1/orders`

<One-sentence description.>

**Request body** / **Query parameters** — table with field, type, required, description.
**Responses** — one block per status code with a real example body.
**Errors** — table of error codes with meaning.

Use the stack's structured component (TypeTable, OpenAPI integration) when one exists rather than hand-rolled tables — see docs-stacks.md.

Writing rules

1. Every fact comes from the source code, read at writing time. Signature, types, defaults, error conditions — find them in the code and copy them. Reference written from memory is fiction with a confident tone.
2. Neutral register throughout. No "powerful", "simple", "handy", "note that you'll love". Adjectives describe constraints ("immutable", "case-sensitive"), not quality.
3. State the negative space: what happens with invalid input, what null means, what is not guaranteed (ordering, stability, thread-safety).
4. Examples are minimal and legal — the smallest call that type-checks and shows the shape. Tutorials motivate; reference examples just demonstrate form.
5. Mark lifecycle states inline: **Deprecated** since v3.1 — use X instead. **Since:** v2.0. Readers on old versions live here.
6. Cross-link types: when a return type or parameter type has its own entry, link it.
7. Alphabetize or code-order consistently within a section and say nothing — the reader should never wonder how a list is sorted.

Generated vs hand-written

If the project has docstring/OpenAPI/typedoc extraction, prefer fixing the source annotations and regenerating over hand-writing parallel reference that will drift. Hand-write the connective prose (section intros, conceptual groupings) around generated cores. If reference must be hand-written, note in your summary that it will need maintenance on API change.

Common defects when improving existing reference

• Advice contamination — "we recommend setting this to 10" embedded in an option table. Move recommendations to a how-to; keep the factual range here.
• Incompleteness — code has 14 options, the table has 9. Diff against source and fill, flagging any option whose purpose you cannot determine from code.
• Default drift — the most damaging stale fact. Verify every default against current source.
• Use-case organization — entries grouped by scenario instead of structure. Reorganize to mirror the code; let how-tos own scenarios.
• Example-as-tutorial — 40-line motivated examples per entry. Trim to minimal demonstrations; link one good how-to.

Style and Voice

Prose craft for documentation. The Style Core in SKILL.md is the law; this file is the case law.

Calibrating to the project's voice

Before writing a word, read the project's best existing pages and extract:

• Formality register — "Heads up: this bites" vs "Note: this behavior may be unexpected". Match it; a register clash reads as outsourced docs.
• Terminology map — the project's words for its own concepts. Build a small glossary from existing docs and code identifiers, and never introduce a synonym. If the code says workspace, the docs never say "project folder".
• Person and mood norms — some projects say "we", some never do.
• Structural conventions — heading capitalization (sentence case vs Title Case), whether pages open with frontmatter descriptions, callout frequency.

When the project has no docs yet, default to: sentence-case headings, "you", imperative instructions, contractions allowed, low-key register.

Sentences

• Lead with the point. Main clause first, qualifications after: "Restart the worker after changing the config" — not "After changing the config, in most cases, depending on your setup, you may need to restart the worker."
• One instruction per sentence. "Run X and then edit Y and restart Z" hides three steps; readers execute sentences one at a time.
• Active voice, named actor. "The CLI writes a lockfile" — the reader learns what does what. Passive voice hides the actor exactly where docs need it most.
• Present tense for behavior. "Returns null if missing", not "will return". Future tense only for genuinely future things (roadmap, deprecation timelines).
• Concrete over abstract. "Responses over 8 MB are truncated" beats "large responses may be subject to truncation".

Words

Banned, with replacements:

• Acronyms expand on first use per page (pages are entered mid-site from search), except those the declared audience certainly knows.
• UI labels, flags, filenames, and identifiers are verbatim in backticks. Bold for UI elements being clicked is acceptable if the project already does it.

Paragraphs and structure

• First sentence of each section does the section's work — readers scan first sentences. If the first sentence is setup, swap it with the payoff.
• Lists for parallel items, prose for reasoning. Three parallel options are a list; a chain of cause and effect is a paragraph. Bullet-pointing an argument destroys its logic.
• Tables for facts with shared attributes (name/type/default). Never put reasoning in table cells.
• Heading depth ≤ 3 (###). Deeper means the page wants splitting.
• Headings make sense alone — the right-rail TOC is read out of context. "Configure the webhook" works there; "Configuration" and "More details" don't.

Code in prose

• Language tag on every fence, always. text for output, bash for shell.
• Shell blocks: no $ prompt prefixes (breaks copy-paste); output goes in a separate text block or after a clear marker.
• Long commands: backslash-continuations at logical boundaries, one flag per line.
• Placeholders only where the value is genuinely the reader's: <YOUR_API_KEY> in SCREAMING form, explained at first use. Knowable values are written out.
• A snippet that depends on earlier snippets says so — or better, repeat the minimum context so each block is independently runnable.

Callouts and emphasis

• Callouts interrupt; that is their cost. Max 3 per page. When everything is highlighted, nothing is.
• Severity honestly: info for "good to know", warning for "you may lose time", danger for "you may lose data". Crying danger over a cosmetic issue burns the signal for the real one.
• Warnings precede the step they protect. A warning after the dangerous command is a postmortem.
• Bold sparingly for the one load-bearing phrase in a section; italics for term introduction; never underline; never ALL CAPS prose.

Audience calibration

State the assumed knowledge in your head before writing, then hold it:

• Novice-facing (tutorials): every term either common knowledge, defined in-line, or linked at first use. No unexplained jargon, no "as you know".
• Practitioner-facing (how-to, reference): domain terms used freely; project terms still linked at first use. Explaining what JSON is insults this reader.
• Contributor-facing (CONTRIBUTING, ARCHITECTURE): codebase vocabulary expected, but team folklore ("the old pipeline", "Dave's service") is not — write for the contributor who joined today.

The most common calibration failure is drift within a page: a tutorial that opens gently and casually drops "just configure the reverse proxy" by step 5. Re-read at the declared level, start to finish.

Inclusive and global readership

• Plain words over idiom — "straightforward", not "a piece of cake"; readers and translators outside your dialect thank you.
• Gender-neutral: "they", or restructure to "you"/plural.
• Examples use placeholder domains (example.com), diverse names, and no real-person data.
• Don't hinge meaning on color alone ("the red button") — name the label.

Tutorial Playbook

A tutorial is a lesson: learning-oriented, practical. The reader is a newcomer who has decided to invest time in your project. Your job is to take them by the hand through a small, complete, successful experience. Success builds confidence; confidence makes users.

The tutorial is judged by one metric: does it work, first try, for every reader?

The contract with the learner

• You decide everything. The learner has no basis for choices yet. One package manager, one OS path (or clearly-fenced tabs), one example app, one happy path.
• Every step produces a visible result. The learner needs constant evidence that things are working: a command's output, a page in the browser, a passing test. Never two consecutive "invisible" steps.
• Minimum explanation. Say only what is needed to complete the step. The learner cannot absorb theory while following instructions — link to explanation pages for "why".
• Guaranteed repeatability. Pin versions. Start from a stated, checkable beginning state. Avoid anything that depends on the reader's environment more than necessary.

Structure template

# Build your first <thing> with <project>

<One or two sentences: what we will build and what the reader will have at the end.
No history, no architecture, no sales pitch.>

## What you'll need

- <runtime> <version or newer> (`<command to verify>` should print ...)
- <other prerequisite, with a verification command>

## 1. <First action — usually install or scaffold>

<Imperative instruction.>

    <exact command>

<What the learner should now see — exact expected output or a description of it.>

## 2. <Next action>

...

## N. <Final action — the payoff step>

<The visible end result: the running app, the response, the rendered page.>

## What you've done

- <capability gained 1>
- <capability gained 2>

## Next steps

- <link to the most natural how-to guide>
- <link to the explanation of the main concept they brushed against>

Writing rules

1. Title names the outcome, not the topic: "Deploy your first function", not "Getting started with functions".
2. "We" voice is allowed and encouraged — the tutorial is a shared journey: "Next, we add the route handler."
3. Number the steps. Use the stack's <Steps> component when one exists.
4. Show expected output after every command that produces any. Use the real output, captured by actually running the command.
5. State the time investment honestly if you state it at all. "10 minutes" that takes 40 destroys trust.
6. Checkpoint after risky steps: "If you see Error: EADDRINUSE, another process is using port 3000 — stop it or change the port in step 3." Only pre-empt failures that are likely, not every imaginable one.
7. End-state must be self-evidently working. "The tutorial is done" is not an ending; "open http://localhost:3000 and you'll see your three todos" is.
8. Keep it small. A tutorial that takes more than ~30 minutes or builds more than one thing should be split. The first success should come early.

What does NOT belong in a tutorial

Common defects when improving an existing tutorial

• Branching paths — "if you're on Docker, do X, otherwise Y" multiplies the untested surface. Collapse to one path or use stack tabs with both paths tested.
• Stale outputs — the doc shows v1 output, the tool prints v3 output. Re-run everything.
• Hidden prerequisites — step 4 silently assumes a database from nowhere. Every dependency appears in "What you'll need" or is created in a step.
• Theory bloat — paragraphs of concept between steps. Move to explanation, keep one orienting sentence.
• No payoff — the tutorial ends after installation. Installation is step 1, not the destination; the learner must do something with the thing.

Verification before shipping

Run the tutorial yourself, in order, from the stated starting state, in this environment where possible. Every command executed, every output compared. A tutorial you have not executed is a draft, not a tutorial. Where the environment makes a step impossible to run (needs a browser, cloud account), verify the commands and config against the codebase and say in your summary which steps were verified by execution and which by inspection.