Writing docs

Docs ship in the same PR as the code they describe (see Adding a feature). This page covers how to write them. Most changes to this site are written with an AI agent’s help. These rules exist so the pages stay readable as they grow.

The rules

1. Describe the product as it is. Write in the present tense about what the code does today. Don’t narrate change (“used to”, “now”, “no longer”, “previously”, “since X”). Leave out ticket IDs, people’s names and project phases. Git and Linear hold the history.
2. Edit, don’t append. When behaviour changes, find the sentence that’s now wrong and rewrite it. Delete what’s no longer true. A PR that only adds paragraphs to a page is usually wrong.
3. Main pages say how to do things. Put rationale, algorithms, edge cases and implementation detail on a page under Reference & deep dives, and link to it.
4. One home per fact. Before writing something down, check whether a page already owns it (see below). If one does, link to it instead of restating it.
5. Write for the reader of that section.
   • User pages are for organisers. Use the UI’s labels, in bold, spelled exactly as the UI shows them (grep the components to check). Never mention tables, columns, functions or internal names.
   • Developer pages name code in backticks. Give file paths where they help someone find the code, not in every sentence.
6. Plain sentences.
   • Lead with the action or the answer. One idea per sentence.
   • Use a list or a table for options.
   • Cut words that add nothing: “deliberately”, “exactly”, “simply”, “just”, “note that”, “in practice”.
   • Avoid chains of em-dashes and parenthetical asides.
   • Don’t defend the design (“this is a deliberate choice, not a limitation”). If the reason matters, give it in one sentence. If it doesn’t change what the reader does, leave it out.
7. Keep pages short. Aim for under 1,000 words on a main user page and 1,500 on a main developer page. Past that, split the page or move detail to Reference.

Where facts live

Fact	Page
Hard rules (cross-schema joins, double guard, EU region, pins)	Architecture
The shared dev database and scripts/supa	Development environment
Environment variables	Environment variables
Tables, columns, RLS	Data model
Server functions and routes	Server functions
Error codes	Error codes
Release and deploy flow	Deployment
What isn’t built yet (developers)	Constraints and planned work
Limits and what isn’t built yet (users)	Limits
Product terms vs code terms	Glossary

Page shape

---
title: Short noun phrase
description: One sentence, shown in search and link previews.
---

One or two sentences: what this page covers and who it's for.

## A task or topic

Steps, a list, or a short paragraph.

## Another task or topic

• Main pages are listed in the sidebar in astro.config.mjs. Add a new main page there.
• Pages under users/reference/ and developers/reference/ appear automatically. Use sidebar.order in their frontmatter to order them.

An example

Before:

The details panel on the right opens the moment you click a node or connection (dragging a node to move it doesn’t select it, so the view stays put while you drag) — including an unplaced one, from the Unplaced list or from a connection that names it.

After:

Click a node or connection to open it in the Details panel. Dragging a node moves it without opening it.

Checking your change

pnpm dev:docs     # http://localhost:4321
pnpm build:docs   # fails on broken Markdown or frontmatter

Before opening the PR, read the page you changed from top to bottom. Check whether it still makes sense to someone who hasn’t seen the diff.