How to write documentation that survives being retrieved

Any retrieval system chops documents into passages and pulls out the ones that look relevant. The passage that gets pulled has no page title attached to it in the reader's mind, no preceding section, and no navigation around it.

So the test for every chunk of your writing is: if this paragraph were the only thing somebody read, would it be true and complete? A paragraph that begins as noted above, this only applies to business accounts fails that test, because the condition it depends on is somewhere else.

This is the single principle underneath everything below. The rest is just the specific ways documents break it.

Headings do two jobs here. They scope the passage that sits under them, and they are the strongest signal about what that passage answers. A heading that reads Returns covers five different questions, which means the passage under it answers all of them badly.

Split it. Can I return something I bought on sale. How long do I have to return something. Who pays for return postage. What happens if I have lost the receipt. Four headings, four short answers, four passages that are each about exactly one thing.

Phrase them in the customer's words rather than in your internal vocabulary. If your team says RMA and customers say sending it back, the heading says sending it back. You can mention the internal term in the body for the people who use it.

The common structure in help content is context, then qualification, then the answer near the end. It reads well and it retrieves terribly, because the first sentences are what carry the most weight and they are the ones describing the background rather than stating the fact.

Invert it. State the answer, then the qualifications, then the context if it is still needed. You have fourteen days from delivery to start a return. Sale items are excluded. Here is how the fourteen days are counted. That ordering is also, incidentally, what a person skimming on a phone wants.

This is the change that most improves an existing help centre with the least rewriting, because it is usually a matter of moving one sentence to the top of each section rather than writing anything new.

Pricing grids exported as images, delivery zone maps, comparison tables screenshotted from a spreadsheet, opening hours set as part of a banner graphic. All of these are invisible to anything reading your site as text, and all of them are extremely common on exactly the pages that answer the most asked questions.

The fix is not to remove the image. It is to make sure every fact in it also exists as text on the same page, either as a real HTML table or as a short list underneath. Yes, this is duplication on the page, and yes, it is worth it, because the alternative is that your most important numbers cannot be quoted by anything.

Downloadable files carry the same problem in a worse form. A price list that only exists as a document a visitor has to open is not part of your site as far as most crawlers are concerned. If it matters, it belongs on a page.

Cross references inside a document are the purest form of the travelling passage problem. See above, as mentioned, per the previous section, refer to the table below: each of these is an instruction that cannot be followed once the passage is separated from its neighbours.

Replace them by repeating the thing they point at. If three sections all depend on the fact that the policy applies only to orders placed online, write that sentence in all three. Repetition inside a document is a cost you pay once when writing. A dangling reference is a cost you pay every time somebody reads the orphaned passage.

It depends is the other one. It is almost always true and never useful. What it means is that you know the conditions and have not written them down.

Implied conditions are the largest single source of confidently wrong answers, because the material genuinely says the thing that got quoted. It just did not say the part about it applying to standard delivery only, because everyone internally knows that.

So make every condition explicit and adjacent. Not free delivery over fifty pounds in one paragraph and standard delivery only in a footnote two screens away, but one sentence carrying both facts. Free standard delivery on orders over fifty pounds, excluding furniture and next day.

Same for numbers. If a diagram shows the size range, write the range in text. If a chart shows the turnaround times, write the times. A reader who can see the chart does not lose anything from the sentence being there, and a reader who cannot see it gains everything.

You do not need to start from a blank document. Take one existing page that answers a high volume question and do four passes. First, split every heading that covers more than one question. Second, move the answer to the top of each section. Third, find every fact that exists only in an image and add it as text. Fourth, search the page for above, below, previous and depends, and fix each hit.

Half an hour per page, and the resulting page is measurably easier for a person to skim as well. That is the useful thing about this list: none of it is a concession to machines. It is ordinary good technical writing that documentation drifts away from when nobody is checking.