Writing Package docs
Every Package's docs follow one shared standard, so people and their Agents read the same material.
Warning: The standard is version 0 and not frozen. Its rules, blocks, and fixed pages can still change; each change gets an entry in its changelog.
Where docs live#
A Package keeps its docs in a docs/ folder inside its own engineering folder. Each file name is the page's slug. Images, videos, and downloads go in docs/assets/. In the app, the docs appear in the main area with an "On this page" list on the right that shows only H2 headings.
The five fixed pages#
| Slug | What it covers |
|---|---|
start | What the Package is, who it is for, a quick start of one to three steps, and a reading order |
how-to | Everyday use; every other page sits under it |
tools | Each tool's type, source, version, install, configuration, and check |
setup | A cost table first, then setup steps grouped by stage |
changelog | Newest first, one heading per date and version |
The slugs never change, even when a title does.
Front matter#
Each page starts with front matter: title, slug, lede, zone, kind, audience, version, and updated. Pages outside the five fixed ones also set parent and order. Only start names the Package and its type.
Writing rules#
- Headings: sentence case, no numbering, no closing punctuation, and no skipped levels. The page title is the H1; the body starts at H2.
- Steps: each step starts with a verb and does one thing. Say where before what. Say what done looks like.
- Lists: at most seven items, with parallel structure. Number them only when order matters.
- Tables: only when each row has three or more attributes, at most five columns, and "none" in empty cells.
- Notes: at most two per page. A note is a left rule with a bold label, with no icon and no fill.
- Text: plain language, no long dashes, repository-relative paths only, terms from the glossary only, and keys written as placeholders. The last section of every page is "See also".
- Agent lines: text for the reader's Agent sits in the body and starts with "Agent:". Anything only the user can do, such as payments, passwords, verification codes, or switches on a phone, tells the Agent to stop and ask.
What is not allowed#
Card grids, tiles, boxes with arrows, pills and badges, callouts with icons or background fills, gradients, raw HTML, and class or style attributes. The checker rejects them.
Checking#
The standard ships one renderer and one checker. The checker tests everything that can be checked mechanically: the fixed pages and slugs, front matter, versions against the changelog, links and anchors, heading levels, note counts, list and table limits, file sizes, and that keys are placeholders rather than real values.