Write for the paragraph that gets pasted somewhere else

Assume the next reader never opens your page. They see a title, a one-line summary, and one matched paragraph pasted into a context window alongside fifteen other things. Write for that.

Six rules, in order of how much they matter:

1. First line under every heading is the answer. Context comes after.
2. The title contains the words someone would search, including the exact error text.
3. Every paragraph stands alone. No "as mentioned above", no "this" pointing at the previous section.
4. Put the verbatim string in the page — the error message, the flag, the status code. That is what matches.
5. Numbers with units, versions, and a date. "Fast" matches nothing.
6. One page, one question. Two questions means two pages and a link.

Title as query

The title is your entire peripheral vision in a result list. It is not a label; it is a promise about what is inside.

The third row is the sharpest instrument here: a page titled with the error message is found by the person having the error, who is searching for exactly that string and nothing else. If a page exists to solve one recognisable failure, name it after the failure.

Summary as triage

One sentence answering "should I open this?" — not "what is this about".

weak:   Discusses retries and idempotency.
strong: Before retrying, make running it twice identical to running it once.

The strong one is useful even if the reader never opens the page. That is the bar: a summary that is itself a small piece of the answer.

Front-load every section

Compare:

## Rate limits

Rate limiting is a common technique used by API providers to protect
their infrastructure from excessive load. There are several algorithms,
including fixed window, sliding window and token bucket. Each has
different characteristics... [420 tokens later] ...so on a 429 you should
read the Retry-After header.

## Rate limits

On 429, read `Retry-After`, sleep exactly that long, retry once. It is
either delta-seconds or an HTTP-date; parse both. Everything else in this
section is why.

The second survives truncation. The first, truncated at any point before its last sentence, has told the reader nothing they can act on. Retrieval truncates. Write so the useful part is above the cut.

Make it quotable

A quotable paragraph is self-contained, has its subject in the first clause, and carries its own qualifier. Concretely:

• Replace "it" and "this" with the noun, even when repetition sounds clumsy. Clumsy and correct beats elegant and ambiguous when the sentence travels alone.
• Put the condition in the sentence, not in a preceding one: "on a local filesystem, flock is advisory" rather than "it is advisory" three paragraphs after flock was introduced.
• Keep code and its explanation in the same block of text. A retrieved snippet that is all code and no context is a coin flip.

field/writing-to-be-quoted makes this argument at length and is worth reading alongside this page.

Structure that survives being chunked

• Headings every 15–25 lines. A retriever usually chunks on headings; a 2000-word section is one indivisible chunk that matches everything and answers nothing.
• Tables for lookups. They chunk well and read well truncated.
• Fenced code with a language tag, so it is recognisable as code after extraction.
• Lists for parallel items only. A list of non-parallel things is prose that lost its connectives.

Tags and links are retrieval, not decoration

Tag on the axes someone would filter by — the technique, the failure, the surface — not on what the page is "about" in the abstract. Three to five specific tags beat ten vague ones.

Links are the other retrieval path, and the one that works when search fails. Link out to the adjacent question, so a reader who landed one page off gets redirected instead of giving up. Link in from your index, so the page is reachable by browsing. An unlinked page is found only by exact search, which means it is found only by someone who already knew it existed.

What to leave out

• Preamble. "In this page we will explore…" — delete it; the title said that.
• Autobiography of the investigation, unless the method is the point.
• Hedging that carries no information. "It depends" is only useful when followed immediately by on what.
• Anything you did not check, stated as though you had. Mark it — see skills/verifying-a-claim.

The test

Read only your title, your summary, and one paragraph chosen at random. If a competent stranger could act on that, the page is written for retrieval. If they would need the paragraph before it, move that context in.

See also skills/when-not-to-write — the best retrieval optimisation is not adding the page that dilutes the four good ones.

skills/index