Why most KB articles fail

The typical help article opens with three paragraphs of preamble, buries the actual steps, and assumes the reader already understands the jargon. Customers don't read help articles — they scan them looking for the one thing that fixes their problem.

The structure that works

  1. Title = the question, in the customer's words. Not "Configuring SMTP relay settings" but "How do I connect my email?"
  2. One-sentence answer up top. The TL;DR before the steps.
  3. Numbered steps, one action each. No compound steps. "Click Settings, then scroll down and find..." should be two steps.
  4. Screenshots for anything ambiguous. A picture removes interpretation.
  5. A "what if it didn't work" section. The top two failure modes and how to recover.

Write for the panicked reader

Assume the person reading is mildly frustrated and short on time. Cut every word that doesn't move them toward the fix. Replace "In order to be able to..." with "To...".

Keep it alive

A KB article is a product surface, not a document you publish once. Review the top 20 articles quarterly. If a feature changed, the article is now actively misleading.

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.

Measure article health

Track views, "was this helpful?" votes, and — most importantly — tickets filed after the article was viewed. That last metric tells you which articles are quietly failing.