--- name: docs-writing description: The writing standard for every page on kolu.dev — the product docs (website/src/content/docs) and the Surface framework docs (website/src/content/surface). Shape limits the build enforces, the review rules beside them, the reference-entry template, and two worked before/after samples. Load before writing or editing any docs page. --- # Writing kolu.dev docs Every page in `website/src/content/docs/` and `website/src/content/surface/` is held to this standard. Rules marked **[lint]** are enforced by `website/test/docs-lint.test.mjs`, which runs in `just website::check` and in the website's Nix build. There is no exemption list and no per-page override. If a rule is wrong, change it here and in the lint, for every page. ## When you change a page Edit the page so it stays true. Do not append a paragraph describing your change, and do not grow a table cell. History belongs in the changelog, not on the page. A new fact goes where a reader looks for it: a row in an existing table, an item in an existing list, or a sentence in the section that owns the topic. ## The reader 1. **One page, one reader, one job.** Every page is one Diátaxis kind: tutorial, how-to, reference or explanation (see the `/diataxis` skill). Content for a different reader moves to the page that owns it, and is linked. 2. **Write for someone using kolu, not someone who built it.** Keep what the reader can see, do, or must know to predict what happens — including limits and failure messages. Cut history ("used to", "is gone"), why a design was chosen (unless the reader has to choose something), how it is implemented, and descriptions of looks the screen already shows. 3. **Order by the reader's questions:** what is it → how do I start → how do I use it → what can go wrong → reference detail. The first screen answers the first two. ## Shape 4. **Opening paragraph ≤ 50 words:** what this is and what you do with it. No history. 5. **Paragraphs and list items ≤ 80 words. [lint]** 6. **Table cells ≤ 40 words. [lint]** A cell that needs more becomes an entry under its own heading. 7. **≤ 300 words of running text under one heading. [lint]** Tables, `` and code do not count. 8. **A page ≤ 2,500 words of running text. [lint]** A page that cannot fit is split. Surface reference pages are exempt (see the variants below). 9. **Three or more parallel things with attributes go in a table or a list**, never inside one sentence. A sequence the reader performs goes in ``. 10. **No paragraph opens with a bold run-in. [lint]** Use a heading, a list or a table. A list item may open with a bold term. 11. **Headings say what the reader finds or does** ("Open the Conductor", "What wakes it"), in words the reader would search for. The test: someone who reads only the table of contents can say where each answer is. 12. **At most two `