Write the Error Message Down Exactly
Why help articles titled with the literal error string beat general troubleshooting pages, and how to build an error index from what your product logs.
Somebody hits a wall in your product at 4pm on a Friday. There is red text on the screen. What they do next is not to think about which category their problem falls into, or to browse your help centre's troubleshooting section. They select the red text, copy it, and paste it into a search box - yours or Google's, whichever is closer.
That is the highest-intent moment in your entire relationship with that person, and most help centres have nothing waiting for it.
The literal string beats the helpful summary
A general article called "Troubleshooting connection problems" has to be found by someone who has already decided their problem is a connection problem, is a troubleshooting matter, and is worth browsing for. Three inferences, any of which can go wrong.
An article titled Connection refused: check that your firewall allows outbound traffic on port 443 requires none of them. It matches the string in front of the user, character for character, in the box they are already typing into.
This is not a subtle effect and it is not really about search engines. It is that you have removed the translation step. The user does not have to describe their problem in your vocabulary, which is fortunate, because they cannot - they do not know your vocabulary, and the whole reason they are searching is that they do not yet understand what has happened to them.
Your codebase already has the list
The reason this rarely gets done is that it looks like a research project. It is not. The list of errors your users see is enumerable, and it is sitting in your repository.
Every user-facing error string in a modern codebase lives somewhere findable - a locale file, a constants module, a set of exception classes with messages attached, or worst case a grep for the phrasing your team uses. That is your index. You do not need production telemetry to start, though it helps enormously with ordering.
Rank by frequency if you have the data and by blast radius if you do not: which of these strings, when a user sees it, means they are completely stuck rather than mildly inconvenienced. Cover the top ten. That is an afternoon's work and it is the highest-yield afternoon available to most help centres.
What an error article contains
Four things, and it is genuinely short - the longer version is a guide of its own.
The literal string, as the title, formatted as code. What it actually means, in one sentence, in plain language - not a restatement of the error, an explanation of the underlying condition. What to do, as steps. And when the answer is "contact us", say so immediately rather than after four things that will not work.
The failure mode to avoid is padding. An error article is read by somebody frustrated and in a hurry. Preamble is actively hostile. There is no need for a paragraph explaining what connections are.
Where this gets awkward
Two places, and they are real rather than decorative.
Error strings change. A message you titled an article with can be reworded in a refactor by someone who has no idea a help page depends on it, and the article silently stops matching. This is the exact drift problem that afflicts every other kind of documentation, except that here the coupling is unusually tight - a single word changing breaks the match. Anything that watches merged changes for user-facing string edits pays for itself fastest on this category of article.
The other is that a long tail of errors is not worth documenting, and the boundary is not obvious. Errors caused by transient infrastructure, or by a state no user can actually reach, will consume effort and help nobody. Frequency data resolves this and most teams do not have it, so the practical answer is to write ten, wait a month, and look at which ones got read.
There is also a category of error that should not exist rather than be documented. If your top error by volume is a validation message people hit constantly, the article is a patch over a design problem, and writing it well enough may remove the pressure to fix it properly. That trade is worth making consciously.
Start here
Grep your codebase for the error strings a user can see. Sort by how stuck each one leaves them.
The top ten are ten articles you can write today, and every one of them will be found by someone at exactly the moment they need it.
About the Author
Simon Moxon has been building SaaS companies since 2009. He's scaled teams to 20+ people, hit £2m ARR, and learned most of the lessons the hard way. Now he's building SupportPages.io - help docs that write themselves when you ship code. He writes about what's changed in SaaS and what hasn't.