Why most KB articles fail
The typical help article opens with three paragraphs of preamble explaining what the feature is and why it exists, buries the actual steps somewhere in the middle, and assumes the reader already understands the internal jargon. It reads like documentation written by someone who understands the system, for someone who understands the system.
The reader is neither. Customers do not read help articles — they scan them, under mild frustration, looking for the one thing that fixes their problem so they can get back to what they were actually doing. Every sentence that is not on the path from their problem to the fix is a sentence they skip, and if there are enough of them, they file a ticket instead. The article existed. It simply failed to deliver in the twenty seconds it had.
This is the gap that makes knowledge bases underperform even when they are large and well-maintained: they are optimized for completeness, and the reader is optimizing for speed.
Title the article with the question, in the customer's words
The title is the highest-leverage sentence in the whole article, because it decides whether the article is ever found. It is what your help center search matches, what Google indexes, and what the reader scans in a list of results.
Title with the customer's phrasing, not your internal noun. Not "Configuring SMTP relay settings" but "How do I connect my email?" Not "Seat provisioning" but "How do I add someone to my account?" The internal term feels more precise, and it is precisely the word your customer will never type. If you want the technical term in there for the people who do know it, put it in the body — search will still find it.
Your own search logs are the fastest way to get this right. Zero-result searches are a list, written by customers in their own words, of the articles you have not written or have titled wrong. That feedback loop is the core of search optimization, and it is worth more than any style guide.
The structure that works
- Title = the question, in the customer's words. As above — this is the one that decides whether anything else matters.
- One-sentence answer up top. The TL;DR before the steps. Some readers need only this, and giving it to them immediately is the fastest possible resolution. It also tells everyone else, in one line, whether they are in the right article at all.
- Numbered steps, one action each. No compound steps. "Click Settings, then scroll down and find..." should be two steps. Compound steps are where scanning readers lose their place, because they read the first verb, do it, and look for the next number.
- Screenshots for anything ambiguous. A picture removes interpretation. Screenshots are also the highest-maintenance element in the article, so use them where the UI is genuinely hard to describe and not as decoration.
- A "what if it didn't work" section. The top two failure modes and how to recover. This section is the difference between an article that deflects and one that produces a worse ticket than no article would have — the customer followed instructions, hit an unexplained wall, and now has to explain a half-finished state.
Write for the panicked reader
Assume the person reading is mildly frustrated, short on time, and possibly on a phone. Cut every word that does not move them toward the fix. Replace "In order to be able to..." with "To...". Delete the paragraph explaining why the feature works the way it does — the person who wants that is not the person filing a ticket.
Prefer the imperative. "Click Save" beats "you will then want to click the Save button." Front-load each step with the verb, so a scanning eye picks up the action without reading the sentence.
Say the hard part plainly. If a step requires admin permissions, say so before the steps, not in a note at the bottom that the reader hits after failing. If something takes fifteen minutes to propagate, say that too. Most of the "the article didn't work" tickets come from a prerequisite or a delay that the author knew about and did not think worth mentioning.
Keep it alive
A KB article is a product surface, not a document you publish once. Review the top 20 articles quarterly, and review any article whose feature shipped a change regardless of its traffic.
An out-of-date help article generates more tickets than no article at all — the customer follows it, it fails, and now they're confused and annoyed.
The maintenance problem is real and it compounds: every article you write is a small recurring obligation, which is why libraries decay quietly as they grow. The structural answer is a scheduled content audit rather than good intentions, and the cultural answer is knowledge-centered service — making article updates a byproduct of answering tickets rather than a separate documentation project nobody has time for.
Measure article health
Track views, "was this helpful?" votes, and — most importantly — tickets filed after the article was viewed. That last metric is the one that tells the truth. A high-traffic article with a high post-article ticket rate looks like a star in your analytics and is actively failing: it is attracting exactly the right readers and not resolving them.
Read those numbers per article, not in aggregate. Aggregate deflection tells you the program is working; the per-article ticket rate tells you which specific page to rewrite this week. That distinction is what turns self-service deflection from a dashboard into a work queue.
The honest test
Your articles are working when the top of your help center is a short list of pages with high traffic and low post-article ticket rates, when your zero-result search log is shrinking, and when agents answering tickets reach for existing articles instead of re-explaining from scratch. If instead agents quietly maintain their own private snippets because "the KB is out of date," the library has already failed — the knowledge exists, it is just not where the customer can reach it.