Most support knowledge bases fail for a reason nobody expects. The content is there, it is accurate, and it is written by people who understand the product. The problem is that it is organized the way the company thinks, not the way customers search.
A knowledge base structured by product module answers the question what does this feature do. A customer arriving at two in the morning with a failed payment is asking why did my card get declined. Those two questions live in different parts of a product-module hierarchy, and the customer will not find the second one.
The best practical guidance on this comes from teams that publish knowledge base advice for a living. Tars frames the objective around the customer question, and Gladly’s writing on customer-centric knowledge bases makes the same argument from a different direction: the unit of organization should be the task the customer is trying to complete. Feed both into one rule and you get the design principle that actually works — organize by customer intent, then map to product structure as a secondary axis.
Start from the tickets, not from the product
The fastest way to build a useful structure is to spend a week reading what customers actually write. Pull the last few hundred conversations, group them by the task the customer was attempting, and count. You will get a distribution that looks nothing like your product documentation, and that distribution is your information architecture.
Three groups almost always dominate. Transactional questions — order status, invoice, refund timing, where is my parcel. Access questions — cannot log in, password reset, verification code never arrived. And policy questions — can I return this, how long is the warranty, does this ship to my country.
None of those three map cleanly onto a feature tree, which is exactly why search-based knowledge bases beat navigation-based ones for this kind of traffic. If the customer has to know which section their question belongs to before they can find the answer, you have moved the work back onto them.
The structure that scales
A layout that survives growth has four layers, and the order matters.
Task-level entry pages. Short pages titled with the customer’s phrasing: my payment was declined, my code never arrived, return an item. Each one answers the question in the first two sentences, then links to detail. These pages are the ones that rank in search and the ones agents paste into chat.
Detail articles. The long version, for the customer who needs the mechanism. Written once, linked from many task pages — a payments article can back four different task pages without being duplicated.
Troubleshooting branches. Decision-shaped content: if this, then that. These should be separate from detail articles, because mixing explanation and branching makes both harder to scan.
Policy pages with dates. Return windows, warranty terms, shipping restrictions. These change, and an undated policy page is worse than no page, because agents and customers will both trust a stale version. Put the effective date at the top.
Write for the second reader
The first reader is the customer with a problem. The second reader is your own agent, mid-conversation, who needs the right paragraph in under ten seconds. Everything that helps the second reader also helps search engines, which is convenient.
That means descriptive headings rather than clever ones, the answer in the first sentence rather than after a preamble, and enough context that a quoted paragraph makes sense on its own. When an agent pastes a paragraph into a chat, a section that starts with as described above is worthless.
Multilingual teams have an extra constraint here. If the knowledge base exists only in one language, agents working in another language are effectively maintaining a private translation of it in their heads, and it drifts. The vocabulary discipline that keeps that from happening is the same discipline described in the translation work on cross-border support, and the mechanics of agreeing on terms is worth reading alongside it.
Maintenance is the real design decision
A knowledge base decays in a specific and predictable way. New features add pages, nobody removes obsolete ones, and within a year search returns two answers for the same question with no indication which is current.
Two rules prevent most of it. First, every article carries a review date, and articles past it are flagged automatically rather than discovered by complaint. Second, the article that answers the most-viewed question gets reviewed on a fixed schedule — traffic concentrates, so maintenance effort should too.
There is a measurable way to know whether any of this is working: whether repeat contact rates fall in the areas you have covered. If customers keep asking the same questions after you publish, the problem is not coverage, it is findability. That link between knowledge content and repeat contact volume is the subject of the piece on reducing repeat contacts and it is the honest test of whether a knowledge base is doing its job.
Where to start this week
Pick your ten most frequent customer questions from last month. Write each as a task-level page, in the customer’s own words, with the answer in the first two sentences. Link them from the places customers already are — the chat widget, the order confirmation email, the ticket form. Then leave the product-module documentation where it is; it is not competing with this, it serves a different reader.
If you want to go further on the operational side, the routing and ownership questions that decide who answers what are covered in the shared inbox rules and the first response time discussion.