Readable

Readers do not read. They scan the skeleton (title, opening, headings, first sentences, bold, tables, code), decide in the first screen whether to stay, read a paragraph until it stops paying, and hold about four ideas at once. They remember what was signaled and forget what sat mid-paragraph. The documents people find easy (GCP docs, Python PEPs, the Stripe API reference) are built for that reader: predictable shape, one job per unit, each kind of information in the form that fits it, prose only where something needs explaining. references/evidence.md has the studies when a rule needs defending.

Writers have the opposite problem. A writer who just did the work knows too much: the mechanism, the history, the names invented along the way. Left alone, the writer compresses all of that into shorthand that only the writer can decode, and explains how things work when the reader asked what happened. Prose is what an agent produces by default and the last thing a reader wants. Structure is the default here. Prose has to earn its place.

The reader's question

Deciding what to say comes first: who reads it, what should change for them, and what they need to hear (/principles: Write for the Reader). This skill shapes what you decided to say.

Every document exists to answer one question. Name it before writing, and put the answer in the first line: