Editorial standard
Every page in this section is written against the rules below. They exist because the docs had grown to 25,757 lines across 81 files — reference material that nobody could onboard from. These rules are what we cut it back with.
Get the taste for it before the rulebook — five pairs of sentences, one survivor each:
Which sentence survives the edit?
The hard limits
| Metric | Limit | Why |
|---|---|---|
| Visible page length | ≤ 250 lines | Past this, nobody scrolls. Split or cut. |
| Code share | ≤ 35% of lines | Above that you've mirrored the source file instead of teaching. |
##/### headings | ≤ 12 per page | More turns the table of contents into a second sidebar. |
| Inline body links | ≤ 3 per page | Every link is an invitation to leave mid-thought. |
| Code block | ≤ 25 lines | Show the lines that carry the idea, not the file. |
"Visible" means lines outside an <Aside>. Content inside a collapsed Aside costs the
reader nothing until they ask for it, so it doesn't count against the budget — that is the
entire point of the component. Measure with:
awk '/^<Aside /{a=1} /^<\/Aside>/{a=0;next} !a{c++} END{print c+0}' page.md
This is not a loophole. A page whose visible line count only passes because you buried the main argument in an Aside has just hidden its own thesis. Asides are for depth a reader can skip, never for the through-line.
If a page can't meet these, it's doing more than one job. Split it by reader intent, not by source file.
The lesson formula
Every non-reference page is a lesson, and lessons have a shape. It's the shape of the best teaching writing on the web (joshwcomeau.com is the house benchmark), and it goes:
- Open with the problem, never the definition. A concrete scenario the operator or developer actually hits — then the concept that resolves it. If your first sentence could open a man page, rewrite it.
- Smallest working example first. A "hello world" the reader can hold, before any generality.
- One concept per step, each introduced by need. The previous step hits a wall; the next concept is the answer. Never front-load a catalog.
- Give every abstraction a mental model. An analogy, a picture, a one-line metaphor ("the whiteboard in the control room"). If you can't produce one, you don't understand it yet either.
- Gotchas are admonitions with narrative titles.
:::warning Gotcha: a poll can never remove a camera— not a bullet in a list. Name the surprise. - Advanced topics go last, in a "Going deeper" section or an
<Aside>— present for the reader who's ready, invisible to the one who isn't. - End with "Wrapping up": a 2–4 sentence recap of the mental model, then exactly one next-lesson link. Every page is a step on a path; say where the path goes.
And the table rule that follows from all of this: a table is for genuinely tabular facts
(value ↔ file ↔ effect), never for prose wearing a grid. API dumps, props tables, and
consumer/trigger matrices mirror the source file — delete them and link the source. The
reference pages that earn tables (feature-map-customization, kusto-queries, the mocking
playbook) announce themselves as reference sheets in their opening paragraph.
The four failure modes
1. Wrong mode. Reference material (exhaustive, every-field-documented) filed where a newcomer will hit it first. Decide which one page you're writing:
- Tutorial — get a newcomer to a working result. Linear, opinionated, no alternatives.
- How-to — solve one stated problem for someone who already has context.
- Reference — look up a specific fact. Tables, not prose.
- Explanation — why the system is shaped this way. The deep-dives.
2. Source-mirroring. If the doc restates the file, it's dead weight that goes stale silently. Link to the source once; explain what isn't obvious from reading it.
3. Fragmentation. A heading every 18 lines destroys signal. Long flowing sections with few headings read better than many stubs.
4. Exit ramps. Deep links scattered mid-paragraph. Put navigation at the end of a page,
and use an <Aside> for detail that used to justify its own page.
Progressive disclosure over more pages
This is the main tool. Detail that is "useful if curious" rather than "required to continue"
goes in an <Aside>, not a new file:
<Aside title="Why not just poll?">
Polling every camera at 1Hz costs ~40 requests/sec at current fleet size...
</Aside>
Rendered, it's one collapsed line until the reader wants it. That single component is what lets a 900-line page become a 200-line page without losing information.
Show before you tell
Lead with the thing that makes the concept obvious, then explain it. A reader who has already seen the behavior reads your explanation twice as fast.
Order that works: one-sentence setup → demo → what you just saw → why.
Interactive demos live in src/components/docs/demos/ in the Documentation repo. Use one
when the concept is a relationship (this input changes that output). Don't fake one for
something that needs real app state — write clear prose instead.
Voice
Write to one engineer, in second person, present tense. Prefer the concrete noun over the category ("the lease expires after 60s", not "temporal constraints are enforced").
State the footgun plainly. If something silently produces wrong results, say "silently produces wrong results" — never "care should be taken".
Before you commit
- Does the first paragraph tell a stranger what this page is for?
- Could you delete 30% and lose nothing? (Usually yes. Do it.)
- Is every code block earning its lines?
- Does it end with exactly one obvious next step?
You made it
If you've read the docs in order, you've gone from git clone to the pixel-to-degree math,
the lease protocol, and the token machinery — the whole app, one lesson at a time. These two
contributing pages exist so the next reader gets the same experience from whatever you write.
Welcome to the team of authors. 🎉