Writing documentation that both a person and a retrieval system can use
There is no second, machine-only copy of a page here — a retrieval system reads the words a person reads. Three habits serve both: put the answer in the first paragraph and let it stand alone, name each thing by its one canonical name rather than by a pronoun, and keep every fact in text where a picture cannot hide it.
Why one text rather than two#
The tempting design is a readable page plus a structured summary for machines. It fails on maintenance: the two copies diverge on the first correction, and the copy nobody reads is the one that goes stale. It also fails on trust — a machine-only summary that says something the visible page does not is indistinguishable from cloaking.
So the alternates that exist here are format conversions, not rewrites: the same words in Markdown, the same page set in a manifest. What differs between a person and a retrieval system is not the content but the unit they take away. A person leaves with an impression of a page; a retrieval system leaves with a passage. Writing for both means making individual passages survive being lifted out.
The answer-first paragraph, and what it has to survive#
The first paragraph is sized deliberately — between 22 and 95 words — because that is roughly the length that can be quoted whole. Its job is to be complete on its own, which rules out three habits that feel natural while writing.
- Opening with the industry
- A paragraph that begins by describing the general problem contains no answer, so a system quoting it quotes nothing useful
- Referring backwards
- "As described above" is meaningless in a passage lifted out of the page, and mildly annoying in the page
- Depending on the heading
- If the paragraph only makes sense under its title, the title has to travel with it and usually does not
The same reasoning governs the question-and-answer blocks. A question with its answer immediately beside it is the shape both readers benefit from — a person scanning for their exact situation, and a system looking for a self-contained passage. It is a writing decision rather than a markup trick, and it only works when the answer actually answers.
Naming the thing every time#
One canonical name per thing, used consistently, is the single highest-value habit for both audiences. A person learns the vocabulary of the product; a retrieval system gets an unambiguous handle. Pronouns and generic substitutes destroy both: a passage that says "the system refuses it" is useless once it leaves the paragraph that said what *it* was.
- Name the real thing —
channel_routes,tenantAdapt, Needs You — rather than "the platform" or "the module". - Use one name for one concept across the whole corpus. A queue that is called two different things in two places is two things as far as any retrieval is concerned.
- Never revive a name the product has retired. Old names are recorded precisely so they can be refused, and a page carrying one teaches a reader — human or otherwise — a vocabulary that no longer resolves.
- Say the query language once, where a reader would naturally say it. A phrase repeated nine times fails the stuffing check and reads badly, which are the same failure seen from two sides.
What to keep out of images#
A fact that exists only inside a picture is invisible to a retrieval system, invisible to a screen reader, invisible to anyone using a text browser or a slow connection, and unsearchable to the person who remembers reading it. That is four losses for one convenience.
| Content | Put it in | Why |
|---|---|---|
| A limit, a default, a version, a status | Text — a sentence, a table row or a definition | It is the fact somebody came for, and it must be quotable |
| A field list or a comparison | A table | A picture of a table is a table nobody can search, sort or copy |
| A sequence of steps | A numbered procedure with the result of each step | The result is what tells a reader whether they are still on course |
| The relationship between parts | A diagram, with the facts stated in text nearby | Shape is what a picture is genuinely better at |
| A screenshot of an error | Text of the message, plus what it means | The message is the searchable part; the screenshot dates faster than the words |
Alternative text is not a hiding place either. It describes the image for somebody who cannot see it; it is not the correct home for a number the page never states in prose.
One page, one question#
Each page here records the single query it intends to be the best answer to, and no two may record the same one. That constraint is doing real work: two pages competing for one question split the evidence that either is the answer, and a reader who lands on the weaker one has to go looking again. When two pages want the same query, one of them is the wrong page and should be written about what it uniquely covers.
- Near-identical titles are flagged for the same reason, because that is the other shape the problem takes.
- The intent record exists for that analysis rather than for text: it is never a list of phrases to work into the prose.
- None of this measures whether an AI system actually reads the result. That is a separate and much harder question — see Measuring whether AI systems can read your site.
Questions#
Does structured markup make a page more likely to be cited?
No claim of that kind is made here, and no figure exists to support one: UNKNOWN. What structured markup reliably does is describe the page unambiguously to something parsing it. Treat it as accurate labelling of content that already stands on its own, never as a substitute for the content.
How long should a page be?
Long enough to state the mechanism and the failure modes. The floor here is 420 words of prose, and it exists because a shorter page almost always describes only the happy path. Padding to reach it is worse than the thin page — spend the words on edge cases and worked examples instead.
Should headings be phrased as questions?
Sometimes, when the section genuinely answers one. A corpus where every heading is a question reads as generated, and the template check will say so once enough pages share the formula. Vary the shape; the constraint that matters is that the section under the heading answers what the heading promises.