What Makes a Good Knowledge Base Article

Start With the Answer

The most important sentence in any knowledge base article is the first one. It should contain the answer to the question the reader came to find. If someone searches "how do I reset my password," the first sentence should tell them how to reset their password, not explain why password security matters.

This inverted pyramid structure, answer first, context after, serves two purposes. Readers who just need the quick answer get it immediately. Readers who need more detail can continue reading. Nobody has to scroll past three paragraphs of background to find what they came for.

One Article, One Question

Every knowledge base article should answer exactly one question or cover exactly one task. Resist the temptation to write comprehensive guides that cover multiple related topics. A single article about "Billing" that covers payment methods, invoices, refunds, and subscription changes is harder to find and harder to use than four separate articles, one for each topic.

When an article starts drifting into a second topic, split it. Link the two articles together so readers can easily navigate between them. This structure makes the knowledge base easier to search, easier to maintain, and easier for AI systems to use when looking for specific answers.

Use Customer Language

Write articles using the words your customers use, not the terminology your internal team uses. If customers call it "my account page" but your product team calls it "the user dashboard," use "account page" in the article title and body. You can include the technical term in the article text for clarity, but the primary language should match what people actually search for.

The best way to find customer language is to read your support tickets. Pay attention to how customers describe problems and features in their own words. Those are the phrases that should appear in your article titles and opening paragraphs.

Write Scannable Content

Most knowledge base readers scan rather than read. They are looking for the specific piece of information they need, not reading the entire article from top to bottom. Structure your articles to support scanning:

• Use descriptive headings. Each H2 and H3 should tell the reader what that section contains. "Step 3: Update your billing address" is better than "Next steps."
• Use numbered steps for procedures. When describing a process, use numbered steps rather than paragraphs. Readers can quickly find where they are in the process and what comes next.
• Use bullet lists for options. When listing alternatives, requirements, or features, use bullets instead of embedding them in paragraph text.
• Bold key terms. Use bold sparingly to highlight the most important words in a paragraph, making it easy for scanning readers to find what they need.
• Keep paragraphs short. Three to four sentences per paragraph is the maximum for scannable content. Long blocks of text discourage reading.

Include Specific Details

Vague articles do not help anyone. "Go to settings and update your information" is less useful than "Click your name in the top-right corner, select Account Settings from the dropdown, then click the Edit button next to your email address." Specific details reduce follow-up questions and make the article genuinely useful.

Include specific navigation paths, exact button names, and expected outcomes at each step. If there are prerequisites, state them clearly at the beginning. If there are common errors, mention what they look like and how to resolve them.

Link to Related Content

A good knowledge base article does not exist in isolation. It connects to related articles that the reader might need next. If an article about changing your password mentions two-factor authentication, link to the article about setting up two-factor authentication. These internal links help readers find additional information without starting a new search, and they help AI systems understand the relationships between topics.

Test With Real Users

Before considering an article finished, have someone who is not familiar with the topic try to follow it. If they get confused or need to ask a question, the article has a gap. The best test is to have a new support agent use the article to answer a real customer question. If they can do it without asking a colleague for help, the article works.