Write Docs

A short, living set of rules for writing documentation in this repo. Update as we learn what works.

0. Write for a reader in a situation

This rule governs every other rule below. Every failure in a doc review traces back to breaking it.

Your reader is a stranger with a job to do. They are not your teammate, they did not read the PR, they do not know the codebase, and they do not care about your reasoning. They arrived with a situation and a question. Serve that, nothing else.

Some readers are agents, some are humans. Write for both: an agent needs unambiguous structure, a human needs to find their case fast. Neither needs your narration.

The four beats

For anything non-trivial (a troubleshooting entry, a decision, a procedure with branches), give the reader these in order. Do not overdo it on simple content.