Writing documentation an assistant can quote correctly
An assistant quotes a passage, not a page. Docs that survive that treatment answer in the first sentence, restate their own subject, and name exact values instead of gesturing at them.
Documentation an assistant can quote correctly puts the answer in the first sentence under each heading, names exact values instead of gesturing at them, and repeats its own subject often enough that any single paragraph still makes sense on its own. An assistant does not read a documentation page the way a person does. It lifts a passage and shows it somewhere else, with no surrounding page and no preceding section. A passage that depends on the paragraph above it becomes wrong the moment it is lifted, and the reader has no way to see that it was ever attached to anything.
A correct documentation page can still be quoted wrongly because correctness on a page is built out of context, and quoting removes the context. A section that opens with "This defaults to false" is accurate in place and meaningless in isolation: the reader is told a default without being told what has it. The same sentence written as "The retry flag defaults to false" survives being moved. Nothing about the page got worse, and everything about the quotation got better.
The same failure appears in cross-references. "As described above, the token expires" is a sentence that cannot survive extraction, because the thing it refers to is gone. Rewriting it as "An access token expires one hour after it is issued" costs six words and removes the dependency. Assistants are not the only reason to do this; a person landing on an anchor link from a search result is in exactly the same position, which is why passages that answer engines can lift tend to be the passages readers like too.
A table row and a list item are already self-contained units, which is what makes them quotable away from the page. Both stop being quotable the moment a cell says "same as above". The construction rules, and the cases where a paragraph is the better shape.
Market4 turns one release note into a changelog page, a blog post, a mail-out and a week of social posts — and then tells you which of them brought anyone back.
| Situation | Hard to quote | Quotable |
|---|---|---|
| Stating a default | This is off by default. | Automatic retries are off by default. |
| Referring to a limit | The limit above applies here too. | The same limit of one hundred items per request applies to search. |
| Describing an error | You will get an error if the token is stale. | A stale token returns HTTP 401 with the message invalid_token. |
| Describing a gap | (no section written) | There is no endpoint for deleting a channel; a channel is removed in the web interface. |
| Version-bound behaviour | This changed recently. | From version three onwards the header is required on every request. |
A heading in documentation should be shaped like the question a reader would type, because the heading is what an assistant matches against and what it usually shows as the label on the quotation. "Authentication" is a chapter title. "How do I authenticate a request?" and "Why does my token stop working after an hour?" are questions, and each one tells both a reader and a machine exactly what the passage under it settles. A page of chapter titles forces every reader to open every section to find out which one contains their answer.
Heading levels matter for the same practical reason. A heading structure that skips a level, or that starts a page at the third level, produces a document outline that does not describe the document, and the outline is one of the few structural signals available to anything reading the page mechanically. One top-level heading for the page, one level down for each section, and no jumps.
An answer that exists only inside a screenshot, a video, a collapsed accordion or a widget rendered after page load is an answer that cannot be quoted. Crawlers and assistants read the text the server returned. A default value shown only in an image of a settings screen is invisible to them, and so is the caption of a diagram if the caption is the place the real number lives. If a fact matters, it belongs in prose on the page, even when it is also shown in the picture.
A quotation is only useful if a reader can get back to the source, so the address of each section has to be stable. Heading anchors that are regenerated from the heading text will change the moment somebody rewords a heading, and every citation pointing at the old anchor lands at the top of the page instead of at the passage. Where a documentation tool allows explicit anchors, set them once and leave them alone, and treat renaming a section as the breaking change it is.
Dates do similar work. A documentation page that says when its statements were last verified lets a reader judge whether the quotation they were shown is still current, and lets you find the pages that have quietly aged. Neither a person nor an assistant can tell the difference between a page that is correct and a page that has not been touched in three years.
No. Every technique that makes a passage quotable also makes it easier to skim: the answer first, the subject named, exact values written out, one idea per paragraph. The reader who lands on a deep link from a search result is in the same position as the assistant, holding a fragment with no context. Writing for that reader is ordinary good documentation practice with a stricter test attached.
Only where there are real questions with short answers. A questions section earns its place when each answer is complete enough to be read on its own, in roughly forty to ninety words. Padding a page with invented questions produces passages that answer nothing, and they compete with the sections that do. Where a question already has a good section, link to the section rather than writing a second version of it.
Specific enough to match. Write the exact status code and the exact message string a caller will see, because that string is what somebody pastes into a search box and what an assistant matches against. Paraphrasing an error as an authentication problem loses the one detail that makes the passage findable. Where the message varies, document the stable part and say which part varies.
State the version or date the behaviour belongs to, in the sentence itself rather than in a banner at the top of the page. A banner is not carried along when a passage is lifted, so a quotation from an outdated page arrives with no warning attached. A sentence that begins with the version it applies to carries its own caveat wherever it goes.
No. A file that lists your pages can help something discover them, but it does not change whether an individual passage survives being lifted out of its page. The work is in the prose: subjects named, answers first, exact values written down. A discovery file with unquotable pages behind it produces confident citations of sentences that stopped making sense the moment they were moved.
A page can be named in an AI answer without ranking for the question, but the case is narrow: the assistant answered from its own weights instead of running a search. Retrieval produces a link. Memory produces a name with nothing behind it.
We split one long numbered prompt into two. Every step after the cut changed number, and the sentences that navigate by those numbers went on pointing at whatever now wore them.