Writing docs
Read this before you add or change a page under docs/. It applies to people and agents alike.
Where a page goes
Pick the page’s reader first, then the folder:
| Folder | Reader | Holds |
|---|---|---|
docs/guide/ |
people who use the board | how to do a task: start work, review a run, plan a cycle |
docs/machines/ |
people who run the agent or host an instance | install, set up, update and remove machines; deploy |
docs/reference/ |
anyone looking up a fact | tables of commands, settings, API calls and file formats, checked against the code |
docs/contributing/ |
people who change Andon | setup, architecture, tests, schema changes, this page |
docs/internal/ |
the team, later | build logs, reviews, acceptance walks; designs for unbuilt work go in docs/internal/specs/ |
If a page serves two readers, split it. A guide page that needs an RPC name, a migration or a “Where it lives” table
is partly a contributing page: move that part to docs/contributing/ and link to it.
Add every new page to the index, under its section. pnpm check:docs fails on a page outside
docs/internal/ that the index doesn’t link.
How a page reads
- Start with what it’s for. The first paragraph says what the feature does and when you’d use it. No history, no “this page describes”.
- Then the steps. A task is a numbered list, one action a step, in the order the reader does them. Name the button or setting exactly as the app shows it, in bold.
- Then the detail. Limits, edge cases and tables come after the steps, for the reader who needs them.
- Say what is true now. Not when it changed, which card changed it, or what it used to be. The git history and the PR keep that.
- Write short. Use short active sentences and call the reader “you”. Give an example rather than a description. Use a table for lookup and a paragraph for reasoning.
- Check the prose. Run the
prose-slop-guardchecker on every page you write or rewrite, and fix what it reports.
A guide page in outline:
# Cycles
Cycles split a team's work into fixed-length blocks, so you can see what fits in the next two weeks.
## Turn cycles on for a team
1. Open **Settings**, search for **Cycles on their own**, and pick the team.2. Set **Length** and **Starts on**.3. ...
## How cards move between cycles
...Settings paths
Settings has six pages: Machines, Automation, Teams, Connections, Workspace and You
(apps/board/src/lib/settings-index.ts, SETTINGS_PAGES). Write a path with →, starting at Settings:
“Settings → Automation → Memory”.
A team page shows six sections: Identity, Repository, Issue tracker, Overrides, Memory and
Archive. The rest (Autopilot, Agents, Planning, Access, Fields, Templates, Runs, Pull requests, Harness) are parked:
they work, but they aren’t on the page. For a setting in one of them, write “search Settings for Blocked cards
wait”, or link its address, /settings/teams?section=runs. Don’t write a click path to it.
Walk every settings path you write in the running app before the PR goes up:
- Run
pnpm dev:demo. It runs on the worktree’s own Postgres, so any worktree can. - Sign in with a demo login it prints.
- Follow the path as the page says it, click by click, at 1440, 1024 and 390 wide.
- If a step doesn’t match, fix the page. If the app is wrong, say so in the PR and open a card for it.
No citations
Readers can’t open the plan or Andon’s own cards. Don’t write:
PLAN.md, or a plan section like§6(the plan is gone)- a plan version like
v2.75 - an Andon card id like
AND-128orAND2-189
Write the fact itself instead: “Team memory is off by default”, not “Team memory is off by default (AND2-209)”.
Example card keys a reader will see on their own board, like WEB-12, are fine.
Retired names
The app no longer shows these. Use the name on the right.
| Don’t write | Write |
|---|---|
| Auto-build | Autopilot |
| Agent ready (the column) | Ready |
| Auto-dispatch (a machine’s switch) | Takes queued work |
| Output globs (a recipe field) | Output files |
| Depends on, Add a dependency | the relation chips: Blocked by, Blocks, Duplicate of, Related |
| the Attachments tab | the Context tab |
| Settings → Models | Settings → Automation (Models offered) |
| Settings → Notifications | Settings → You (Notifications) |
| Settings → Integrations | Settings → Connections |
| Settings → Memory | Settings → Automation → Memory |
| Settings → Projects, → Agents, → Providers, → General, → Account | the six pages above; search Settings for the setting |
| Teams → a team → General | Teams → a team → Identity |
| Teams → a team → Autopilot (or another parked section) | search Settings for the setting |
One near miss: Max runs is still the label on the phone’s machine list, but Settings → Machines shows Runs at once, and its edit dialog says Max concurrent runs. Name the one the reader is looking at.
When you rename something in the app, add its old name to this table and to RETIRED in scripts/check-docs.lib.ts
in the same PR.
Which doc a change touches
| Your change | Update |
|---|---|
| Something a board user sees or does differently | its page in docs/guide/ |
| A setting’s name or place | every page that gives its path (search docs/ for the old name), and the retired-names table if the old name is gone |
| Installing, updating or removing the agent; a host recipe | its page in docs/machines/, or deploy/<host>/README.md |
| A CLI command or flag, a policy key, an MCP tool, an API operation, an env var | its row in docs/reference/ |
| How to build, test or change Andon itself | its page in docs/contributing/ |
| A design for something not built yet | a new page in docs/internal/specs/, never docs/guide/ |
| A finding from a spike, a review or an acceptance walk | docs/internal/ |
| Nothing a reader would do differently | no doc; the commit message and PR body say it |
Edit the page that covers the feature. Don’t add a “what changed” section or a dated note to it.
The docs lint
pnpm check:docs fails on the cases below. Run it before you push: CI runs only by hand, in its lint job.
- a page under
docs/that isn’t in a section folder or a stub (see below) - a page outside
docs/internal/that the index doesn’t link - a relative link, in any page outside
docs/internal/, to a file that doesn’t exist - a citation or a retired name in
docs/guide/,docs/machines/,docs/reference/or a stub
Code blocks, inline code and HTML comments are skipped. docs/internal/ is exempt from every rule.
There is no allowlist. A page that breaks a rule gets fixed, not excused. The rules live in
scripts/check-docs.lib.ts, with tests beside them in scripts/check-docs.test.ts.
Moving a page
When you move or rename a page, find what links to its old path: git grep 'docs/<page>.md'. Repoint what you can
edit (other pages, code comments, skills, READMEs). Applied migrations and .andon/memory entries can’t change, so if
one of them cites the old path, leave a stub there:
# Old title
This page moved to [guide/new-page.md](guide/new-page.md).A stub sits directly under docs/, has one title and at most five lines below it, and links a page in a section.
The lint lets it stay outside a section, and checks it for citations and retired names like a guide page. List it in
the index beside the page that replaced it.
