How to Write a Perfect Support Knowledge Base Article

IN THIS ARTICLE

1. 01Start with the question, not the feature
2. 02Structure: the format that works
3. 03Tone: how to write for someone who is frustrated
4. 04When to use screenshots vs text
5. 05SEO for help centre articles
6. 06Keeping documentation up to date
7. 07Measuring article effectiveness
8. 08Using AI to maintain documentation quality at scale

A good knowledge base article deflects a support ticket. A bad one causes two: one from the customer who found the article and still could not solve the problem, and one from the agent who has to explain why the documentation was wrong.

Most knowledge base content is written by people who know the product extremely well, for people who are encountering it for the first time. The expert knowledge is actually a liability here: it creates the "curse of knowledge" where the writer skips steps, uses internal jargon, and assumes context the reader does not have. This guide is about writing around that problem deliberately.

Start with the question, not the feature

The most common mistake in knowledge base writing is organising content around features rather than customer questions. Your product team thinks in features. Your customers think in problems. They search for "how do I change my billing email" not "Account Settings overview."

Before writing any article, define the specific question it answers. A good article answers one question well, not three questions adequately. If you find yourself writing an article that tries to cover "all account settings," stop. Break it into individual articles: "How to change your billing email," "How to update your password," "How to add a team member." Each one targets a specific search query and provides a complete answer.

Structure: the format that works

Knowledge base articles are not essays. Customers come to them with a specific problem and want to find the answer as quickly as possible. Dense prose paragraphs slow them down. The format that works consistently:

1. 1Title: the question the customer asked, in plain language. "How to export your conversation history" not "Conversation History Export Feature."
2. 2One-sentence summary: what this article covers and what the customer will be able to do after reading it.
3. 3Prerequisites (if any): "You need Admin access to do this" upfront, not buried in step 8.
4. 4Step-by-step instructions: numbered, one action per step. Each step should be completable in under 30 seconds.
5. 5Expected outcome: what the customer should see or have after completing the steps. This is the most commonly omitted section and the most useful: it tells the customer whether they did it right.
6. 6Troubleshooting: the two or three things that most commonly go wrong and how to fix them.
7. 7Related articles: two or three links to connected topics the customer might need next.

Tone: how to write for someone who is frustrated

Customers reading support documentation are usually not in a good mood. They are either stuck on something or cannot find something. The tone of your documentation should acknowledge this implicitly through clarity and directness, not through excessive cheerfulness that comes across as tone-deaf.

• Be direct: "Click Save" not "You may want to consider saving your changes by clicking the Save button when you are ready."
• Use the active voice: "Enter your email address" not "Your email address should be entered."
• Avoid jargon: use the exact label names from the product UI. If the button says "Add member," your article should say "Click Add member," not "Click the team invitation button."
• Short sentences: aim for an average sentence length under 20 words. Long sentences in instructional content make steps harder to follow.
• No preamble: do not open with a paragraph about the importance of the feature. Go straight to the steps.
• Empathy, not sympathy: "Here's how to fix that" is better than "We're sorry to hear you're having trouble." One is actionable, one is just words.

When to use screenshots vs text

Screenshots are not always helpful. The instinct to add a screenshot to every step is understandable but creates two maintenance problems: every UI change requires a documentation update, and screenshots of complex screens can be harder to read than a clear text instruction.

Use screenshots when: the UI element is hard to describe precisely, the customer needs to verify they are in the right place, or the outcome (what success looks like) is easier to show than to describe.

Do not use screenshots when: the step is a single clearly-labelled action ("Click Save"), the screenshot adds no information beyond what the text already says, or the element is likely to change and you cannot guarantee documentation currency.

SEO for help centre articles

Many customers will find your knowledge base articles through Google before they find your support widget. Optimising for search is worth the small amount of extra effort it requires.

• Title as H1: your article title should be the page's H1 heading and should contain the phrase customers actually search for.
• URL slug: use the customer-facing question form. /docs/how-to-export-conversations ranks better than /docs/feature-export-module.
• Answer in the first paragraph: Google's featured snippet algorithm pulls the clearest answer to the question. Put your most direct answer in the first 150 words.
• Internal linking: link to related articles from within the body. This improves discoverability in your own help centre search and distributes authority across pages.
• Meta description: write a 150-character description that previews the answer. "Learn how to export your full conversation history as CSV or JSON in three steps" is better than "Everything you need to know about exports."

Keeping documentation up to date

Outdated documentation is worse than no documentation. A customer who follows outdated steps and ends up somewhere different from the expected outcome will be more confused than if they had just asked support directly.

Build documentation updates into your product release process. Every feature change or UI update should trigger a documentation review for all affected articles. This does not have to be the engineer's job: a dedicated documentation owner or a support team member with product access can keep pace with a monthly release cadence.

Add a "last reviewed" date to every article. This gives customers a signal about currency and gives your team a clear indicator of which articles have gone the longest without review.

Measuring article effectiveness

You cannot improve documentation you do not measure. The most useful metrics for knowledge base effectiveness:

• Article deflection rate: the percentage of customers who viewed the article and did not subsequently open a support ticket on the same topic. The single most important metric.
• Article rating: simple thumbs up/down or 1-5 star rating at the end of each article. Low-rated articles need immediate review.
• Search-to-click rate: when customers search your knowledge base, are they finding and clicking relevant articles? Low click rates on searches mean your titles are not matching customer language.
• Support ticket cross-reference: which ticket categories correlate with which knowledge base articles being viewed? If customers are reading the article and still opening tickets, the article is not answering the question.
• Time on page: unexpectedly short times may indicate the customer did not find what they needed. Long times may indicate the article is hard to follow.

Delyt's knowledge base module tracks all of these metrics automatically and surfaces articles with low deflection rates for review. You can explore the full knowledge base capability on the product page.

Using AI to maintain documentation quality at scale

As your knowledge base grows, maintaining consistency becomes harder. AI can help in two ways: generating first drafts from product specifications or ticket data (which a human editor then refines), and flagging articles that have gone without review for too long or that are generating tickets despite high view counts.

The best knowledge bases are not written once and forgotten. They are living documents that improve over time based on what customers are actually searching for, what tickets are still being opened, and what the support team learns from real conversations.