Source material
The error text is the question, so the article has to contain it
Troubleshooting content fails in retrieval for a reason that has nothing to do with how good it is. People do not describe their problem, they paste it. The string in the box is a machine-generated sentence from your own software, and if that string appears nowhere in your documentation there is nothing for a matcher to match, however thoroughly the underlying cause is explained.
Why this one is harder than it looks
Start with the query itself. A person with an error in front of them copies it and pastes it, punctuation, error code and all. That is the most specific input any assistant will ever receive about your product, and it is completely wasted if the article about that error describes it as a connection problem rather than quoting the words the software actually printed. Matching is done on meaning, but meaning is derived from the words present, and the words present in the customer's message are your software's words.
Then there is the habit of writing symptoms as causes. Headings like Authentication misconfiguration and Stale token cache are how the person who fixed the bug thinks about it. They are not how anybody experiencing it thinks about it. The customer knows they clicked a button and nothing happened. An article whose every heading names a mechanism is an article organised entirely around knowledge the reader does not have yet, which means none of its headings resemble anything they will ever ask.
Decision trees suffer worst of all. Diagnosis is genuinely branching work, and the honest way to write it is a tree: if A, do this, if not A, check B. Flattened into prose it becomes a chain of if that does not work clauses, each of which is a perfectly extractable passage that reads as a standalone instruction while actually being conditional on everything above it. A passage beginning if that does not solve it is a passage that has lost the thing it was conditional on.
Finally, the organising instinct is usually wrong. Documentation gets written one page per subsystem, because that is how the software is built and how the team is organised. But nobody arrives with a subsystem. They arrive with a symptom, and a single page covering everything that can go wrong with one subsystem is a page where every passage looks like every other passage to a matcher, and where the right cause is buried among five wrong ones.
What it has to contain
Structure rather than wording. A passage pulled out of this document has to stand on its own, because that is the only form in which it will ever be read.
| The error string, quoted exactly, near the top | The literal text the software produces, including the code and the punctuation, in the opening lines. Not paraphrased, not tidied up, not translated into plain language. Where the message contains a variable part, quote it with the variable left in place and say what varies. |
|---|---|
| A symptom heading written in the customer's words | What they are looking at, not what is wrong underneath. Nothing happens when I click Connect beats Handshake failure, because the first is a sentence somebody would actually type. |
| One observable test per cause | Something the reader can check to tell this cause apart from the others: a message, a setting, a status, a piece of the interface. A list of possible causes with no way to distinguish them sends everybody round every one. |
| Each branch written as its own complete condition | Every conditional step restates what it is conditional on. If the status still shows Pending after five minutes, rather than if that did not work. |
| One page per symptom | The unit of the document is the thing that happened to the customer, not the component that failed. Several symptoms sharing a cause link to a common explanation rather than sharing a page. |
The rewrite, in order
Put the literal error text into the document
Collect the actual strings. Not from memory and not from the design document, from the software: the exact sentences it prints, including codes, capitalisation and any trailing detail. If several versions of the product produce different wording for the same condition, collect all of them.
Place them in the article as quoted text near the top, under a line saying what the message is. Where a message includes a changing part, an identifier or a hostname, keep the surrounding words verbatim and say plainly which part varies. The unchanging words are what carry the match, and they are usually the majority of the sentence.
One page should quote one message, or a small set of messages that genuinely mean the same thing. Ten unrelated errors quoted on one page dilutes every one of them, because the page as a whole is then about nothing in particular and its passages all half-match everything.
Rename every heading from the mechanism to the experience
Go through the headings and rewrite each one as the sentence a customer would type. The mechanism does not disappear, it moves into the body where it belongs, explaining why the symptom happens. The heading is the part that has to look like a question.
This is the single change that moves the most traffic, because headings tend to open passages, and a passage that opens with the customer's own phrasing is a passage that matches their phrasing. It also exposes duplicates: two mechanism headings often turn out to describe one experience, and they should merge.
Keep the mechanism name in the body text anyway. Somebody technical will search for it, and it costs nothing to have both the plain description and the internal name present in the same passage.
Unflatten the decision tree
Find every if that does not work, otherwise, still not fixed and try the next one. Each of these marks a place where a passage depends on a condition stated in a passage above it, which is exactly the dependency that does not survive extraction.
Rewrite each branch to name its own condition. Instead of if that does not work, check the allowlist, write if the status is still showing as blocked after the change, check the allowlist. The restatement is what makes the branch legible on its own, and the article reads barely differently to a human going through it in order.
Where the tree is genuinely deep, three or four levels, that is a signal the page is covering too many symptoms. Split at the first branch: each top-level branch becomes its own page with its own symptom heading, and the shared setup becomes a short section repeated in both. Repeated setup is cheaper than a tree that cannot be entered in the middle.
Reorganise by symptom and let causes be shared
Take the subsystem pages and invert them. List every distinct thing a customer can observe going wrong, and give each one a page. Several of those pages will share a cause, and that is fine: each names the cause, gives the test that confirms it, and links to a single explanation of the mechanism if the mechanism needs more room.
Order the causes on each page by how often they are actually the answer, not by how easy they are to explain or how interesting they are. A reader working down the list is spending their time in the order you chose for them, and putting the rare and elegant cause first is a decision to waste it.
When a symptom has exactly one cause, say so at the top rather than presenting a list of one. An assistant answering from that page will then give a definite answer instead of a hedged list, which is the correct outcome and the one your document is now making possible.
What happens if you skip it
The refusal that should have been an answer
The signature failure of an unrewritten troubleshooting library is not a wrong answer. It is nothing at all. A customer pastes an error string, no passage in the material resembles it closely enough to clear the match threshold, and the assistant declines using the wording the owner wrote. The article explaining that exact error is sitting in the index, indexed under a heading naming a mechanism the customer has never heard of.
The second failure is worse and less visible. A branch passage is retrieved, one that begins with the equivalent of if that did not work, and it is answered as the first thing to try. The customer is sent to the second remedy for a problem they have not confirmed they have, undoes a setting that was correct, and now has two problems.
Both cost the same thing: the deflection you built the assistant for, on precisely the questions where it would have been most valuable. Error messages are the highest-intent thing anybody ever sends a support channel, because the person is stuck right now and has already tried the obvious. Failing there is failing on the good half of the volume.
Check it against this
Before you index it
- Every error string appears verbatim in the article about it
- Headings read like sentences a customer would type
- Each cause has one observable check that rules it in or out
- No passage begins with if that does not work
- Causes are ordered by how often they are the answer
- One symptom per page, with shared causes linked rather than duplicated
- Single-cause symptoms say so instead of listing one option
Questions
- Our error messages change between versions. Which one do I quote?
- All of them that are still in the field, on the same page, labelled by version. The unchanging part of a message is usually most of it, so several variants sit together comfortably. Quoting only the current wording makes the page invisible to everybody who has not upgraded, which is exactly the group most likely to be stuck.
- Should I include internal error codes?
- Yes, if the customer can see them. If a code appears anywhere in the interface, in a log the customer can read, or in a support email, it is something they will paste, and it is the most distinctive string on the page. Codes that only exist in your own logs are not worth including.
- Is one page per symptom not going to produce a lot of very short pages?
- It will, and that is the correct shape here. A short page about one symptom is a page where every passage is about that symptom. A long page about a subsystem is a page where the right passage is competing with several near-identical wrong ones for the same question.
Keep reading
- The question this document answersWhat the visitor is really asking, and where an answer becomes a handover.
- How to turn an onboarding guide into a source an assistant can answer fromOnboarding guides are sequences. Retrieval hands back a middle. Here is how to rewrite the steps, the prerequisites and the screenshots.
- How to make an API reference answerable and not just completeGenerated reference pages are mostly boilerplate, which makes every passage look alike. Fix the tables, the examples and the version paths.
- Why indexing your changelog makes the assistant describe the pastRelease notes record moments. Questions are about now. How to stop an assistant quoting a change that was later reverted or superseded.
- Every kind of source materialWhat to feed an assistant, and the surgery each document needs first.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.