Knowledge Base Design

---
name: knowledge-base-design
description: Build self-serve documentation that answers questions before they become tickets, organised by what people search for. Use when the same questions arrive repeatedly.
---

# Knowledge base design

A knowledge base earns its keep by deflecting tickets, and it deflects
nothing if people cannot find the article or do not trust it. Both
failures are usually organisational rather than editorial.

## Method

1. **Write from actual tickets.** The most common questions, in the
   words customers used, rather than the topics you think need
   documenting (see support-analytics).
2. **Title with the question.** How do I cancel my subscription matches
   what people search; Subscription management does not (see
   query-understanding).
3. **Answer in the first paragraph.** Prerequisites and context after,
   because most readers need only the answer.
4. **One article per question.** Comprehensive pages covering eight
   related things rank poorly and answer none of them directly.
5. **Keep it current or delete it.** A wrong article is worse than a
   missing one, because it costs the customer time and then a ticket
   anyway.
6. **Link from where the question arises.** In-product help at the point
   of confusion deflects far more than a help centre people must think
   to visit (see in-app-messaging).
7. **Measure deflection, not pageviews.** Whether the article prevented
   a ticket is the metric; traffic to an unhelpful page is a cost.

## Boundaries

A knowledge base handles common cases; unusual problems still need a
person, and hiding contact options to force self-serve generates anger
rather than deflection. Articles need owners or they rot. Translation
multiplies maintenance (see translation-workflow).