There's a useful piece of research that ran thousands of tests on AI agents doing real tasks against real documentation. The interesting result wasn't what they got wrong. It was how little they got wrong, once they had the right page in front of them.

Comprehension was close to solved. Give an agent the correct passage and it will read it about as well as a careful person would. The failures clustered somewhere much less glamorous: it couldn't find the page, or it found the wrong one and had no way of knowing.

Everyone is optimising the wrong half

Most of the advice floating around is about making writing more machine-friendly. Simplify the language. Use consistent structure. Add schema markup.

Fine advice, mostly. But it's all aimed at the reading step, and the reading step is not where this breaks.

The retrieval step — which page, which passage, is it even reachable — is where the failures are, and it's the part almost nobody works on because it doesn't feel like documentation work.

What actually decides whether you're found

Whether the page can be reached at all. If your docs render client-side and the crawler saw an empty shell, nothing else matters. This one is worth checking before anything else, because it's invisible from the inside.

Whether your words match the question. A customer types "team space", your article says "workspace", and nothing outside your company knows those are the same thing. That mismatch fails silently.

Whether one page owns the question. Three half-articles on one topic split the signal three ways, and which fragment gets picked is close to arbitrary.

Whether the passage stands alone. A section that depends on the one above it will be retrieved without it, and then either discarded or used wrongly.

The reframe worth taking away

If you've been treating this as a writing problem, you've been polishing sentences on pages that were never delivered. That's a genuinely demoralising way to spend a quarter, and it's the most common version of this work we see.

The order that works is: make sure it can be reached, make sure it can be found, make sure the passage survives on its own — and only then worry about whether the prose is elegant.

None of which means writing doesn't matter. It means the writing is the last step, not the first, and the three steps before it are the ones nobody is doing.

So before you rewrite anything, go and check that the page can be reached at all. It is the least interesting question and the one most likely to be the answer.