How to Build a Product Knowledge Base People Actually Use

Most help centres are written once and never read

The usual pattern: a support backlog gets painful, somebody spends a fortnight writing thirty articles, the pages go live, and tickets barely move. Six months later the articles describe a version of the product that no longer exists, and the team concludes that customers "don't read documentation".

Customers read documentation constantly. What they will not do is hunt. A knowledge base only reduces support load when the right article is reachable at the moment of confusion, in the words the customer would use, and is currently true.

What to write first

Do not start from a feature inventory. Start from your support inbox.

1. Export the last 300 tickets.
2. Tag each with the underlying question, not the phrasing.
3. Count. The distribution will be brutally uneven — typically a handful of questions account for the majority of volume.
4. Write those, in order, and stop when the tail flattens.

Twenty accurate articles covering real questions outperform two hundred covering the feature list. The long tail can wait until the head is genuinely handled.

Information architecture

Five top-level sections cover almost every product. Resist adding a sixth; depth is cheaper than breadth, and a long top-level menu is a sign you organised around your own org chart.

The anatomy of an article

Put the answer first. A reader who has to scroll past three paragraphs of preamble to learn whether they are in the right place will go back to the search results, or open a ticket.

Surfacing articles at the right moment

Publication is not distribution. Three placements do most of the work:

• In-product, contextually. A help link on the screen where the confusion happens outperforms the same article buried in a help centre by a wide margin.
• In the support reply. Every agent answer should link the article; if none exists, that is the signal to write one.
• In search. Help articles rank for long-tail problem queries, which is often a meaningful acquisition channel in its own right — people search their error message before they search your product name.

Keeping it true

Documentation rots silently, and stale documentation is worse than none: it costs trust as well as a ticket. Three mechanisms keep it honest:

1. A named owner per section. Not "the team".
2. A release checklist item. "Which articles does this change affect?" belongs in the same list as the changelog.
3. A quarterly sweep of the top 20 articles by traffic. Twenty articles is an afternoon, and those twenty carry most of the value.

Measuring deflection

Page views are the metric to ignore. A heavily viewed article about a confusing feature may mean the feature needs fixing, not that the article is succeeding.

Feeding a support chatbot

A retrieval-based assistant is only as good as the corpus behind it, which makes the knowledge base a prerequisite rather than an alternative. Practical constraints worth knowing before you wire one up:

• Structure matters more than volume. Clear headings and one topic per article retrieve far better than long omnibus pages.
• Contradictions are poison. Two articles disagreeing about the same limit will produce confident wrong answers.
• Ground answers in citations so users can verify, and so you can see which article produced a bad answer.
• Keep a human escape hatch on every conversation.

The sequencing point matters commercially: write the articles first. A chatbot on top of a thin or stale knowledge base industrialises the wrong answer.

Frequently asked questions