doc-style

Markdown documentation style

Markdown documentation prose — RFCs, ADRs, files under docs/, and READMEs — follows the same one-paragraph-per-line rule as commit messages. Write each paragraph on a single line; do not hard-wrap prose to a fixed column. The renderer reflows it to the reader's display width, whereas manual mid-paragraph line breaks render as ragged text and turn a one-word edit into a multi-line diff. Reserve hard line breaks for genuinely line-oriented content (lists, tables, code blocks), and use blank lines to separate paragraphs. Apply this to prose you add or edit; reflow surrounding hard-wrapped paragraphs only when you're already changing them, not as a sweeping rewrap.

Introduce before use; prefer mechanism over property

Design docs — RFCs especially — must read as practical descriptions of what is being built, not fluent prose that leans on terms the reader has not met. Two habits cause that defect; avoid both.

Introduce a named component before referring to it. The first time a concrete artifact appears (a token, a CA, a store, a config type), define it in one breath — what it is, who creates it, where it lives, its lifetime, and the problem it solves — using the indefinite article ("each run gets a proxy token, a random value the host…"). Only after that introduction may later text use the definite article ("the proxy token"). A first mention written as "the per-run token" presupposes a definition the reader was never given and forces them to reverse-engineer it from usage. When a doc has many such artifacts, define them once in a short "New components" inventory near the top of the design section, then refer back to it; if a forward reference is genuinely unavoidable, mark it explicitly ("the per-run CA, defined below"), never as a bare "the per-run CA".

State the mechanism before claiming the property. Do not assert a guarantee ("isolates runs", "bypass-safe", "fail-closed") on its own — first describe the concrete behavior that produces it, then let the property follow as a consequence. "X isolates runs from each other" is an unearned claim; "the host gives each run a token the proxy checks per connection, so one run cannot drive another's traffic" is a mechanism the isolation falls out of. The same applies to hype adjectives that assert quality without showing it ("powerful", "seamless", "robust", "simply", "easily") — describe what the thing does and let the reader judge. When reviewing prose you wrote, scan for definite-article first mentions, bare property claims, and hype adjectives, and fix each at the point of use.