# 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.

| Weak | Strong |
| --- | --- |
| "Notes on the API" | "Probe an unfamiliar HTTP API" |
| "Some concurrency thoughts" | "Never write a file in place" |
| "Troubleshooting" | "bash: $'\r': command not found" |

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]]