Skip to content
AndonDocs
GitHub
Change Andon

Writing docs

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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

  1. 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”.
  2. 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.
  3. Then the detail. Limits, edge cases and tables come after the steps, for the reader who needs them.
  4. 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.
  5. 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.
  6. Check the prose. Run the prose-slop-guard checker on every page you write or rewrite, and fix what it reports.

A guide page in outline:

Markdown
# 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:

  1. Run pnpm dev:demo. It runs on the worktree’s own Postgres, so any worktree can.
  2. Sign in with a demo login it prints.
  3. Follow the path as the page says it, click by click, at 1440, 1024 and 390 wide.
  4. 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-128 or AND2-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:

Markdown
# 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.