How to Write a Knowledge Base Article (with Templates)

A knowledge base is only as good as the articles inside it. A poorly written article wastes the customer's time, fails to solve their problem, and generates a support ticket anyway, defeating the entire purpose. A well-written article solves the problem in under two minutes and makes the customer feel capable.

This guide shows you how to write knowledge base articles that actually work, with templates you can use immediately.

What Is a Knowledge Base Article?

A knowledge base article is a self-contained piece of content designed to answer a specific customer question or guide them through a specific task. Unlike blog posts or marketing content, a knowledge base article prioritizes clarity and utility over engagement or persuasion.

There are four common types: how-to guides (step-by-step instructions), troubleshooting articles (diagnosing and fixing problems), FAQs (short answers to common questions), and reference articles (definitions, specifications, and policy explanations).

Why Writing Quality Matters

• Deflection depends on clarity. An article that confuses customers generates more tickets than it prevents. Clear writing is the difference between a knowledge base that works and one that does not.
• Trust is built through accuracy. Inaccurate or outdated articles erode customer confidence in your documentation and, by extension, your product.
• Search depends on the right words. Customers search using their own vocabulary. If your article uses different terms than your customers do, search will not surface it.
• Agent efficiency improves. When agents can link to a well-written article instead of typing a custom explanation, they handle more conversations per hour.
• Maintenance cost decreases. A well-structured article is easier to update when the product changes. A wall of text requires a full rewrite.

How to Write a Knowledge Base Article

Step 1. Start with one specific question

Every knowledge base article should answer exactly one question or guide the reader through exactly one task. If you find yourself covering two distinct topics, split them into two articles.

Good article scopes:

• "How to connect your email account"
• "What to do when you see error code 403"
• "How to export your data as a CSV"

Bad article scopes:

• "Everything you need to know about email" (too broad)
• "Email setup, forwarding, and troubleshooting" (three separate articles)
• "Settings overview" (not a question customers ask)

Start by writing the customer's question as your working title. You can refine it later, but keeping the question front and center ensures you stay focused.

Step 2. Write a title that matches how customers search

Your title should use the exact words a customer would type into a search bar. Customers do not search for "Email Configuration Parameters." They search for "How to set up email forwarding."

Title formulas that work:

• How to [action verb] [object] - "How to reset your password"
• What to do when [problem] - "What to do when your email is not sending"
• Why [thing] is happening - "Why your messages are going to spam"
• [Object] not working - "Two-factor authentication not working"

Avoid:

• Internal jargon or product-specific terminology that customers would not know
• Clever or creative titles that sacrifice clarity
• Titles that do not match the article content

If your product uses specific terminology (like "Workspaces" instead of "Projects"), include both terms: "How to create a Workspace (project)."

Step 3. Write a one-sentence introduction

The introduction should tell the reader what this article covers and confirm they are in the right place. Keep it to one or two sentences.

Example: "This article explains how to connect your Google Workspace email account to TidySupport so your team can manage support emails from a shared inbox."

Do not include background information, product history, or lengthy context. Customers reading a knowledge base article already know they have a problem. They want the solution.

Step 4. Structure the body for scanning

Most knowledge base readers do not read articles from top to bottom. They scan for the specific piece of information they need. Structure your article to support this behavior.

For how-to articles, use numbered steps. Each step should:

• Start with an action verb ("Click," "Select," "Enter," "Navigate to")
• Describe one action per step
• Include the exact names of buttons, menus, or fields as they appear in the product
• Add a screenshot below the step showing the relevant part of the interface

Example:

Step 1. Navigate to Settings

Click your profile icon in the top-right corner, then select Settings from the dropdown menu.

Step 2. Select Email Accounts

In the left sidebar, click Email Accounts. You will see a list of all connected email addresses.

Step 3. Click Add Email Account

Click the Add Email Account button. Choose your email provider from the list (Google Workspace, Outlook, or Custom SMTP).

For troubleshooting articles, use a problem-cause-solution structure:

Symptom: Emails are not appearing in your shared inbox.

Common causes:

• Your email forwarding rule is not active.
• The connected email account's credentials have expired.
• Your email provider is blocking the connection.

Solution: Check each cause in order. [Steps follow.]

For FAQ-style articles, use a question as the heading and a concise answer below. Keep each answer to one or two paragraphs.

Step 5. Use plain language

Write at a reading level that any customer can understand, regardless of their technical background. This is not about dumbing things down. It is about removing unnecessary complexity.

Rules for plain language in knowledge base articles:

• Use short sentences (under 20 words when possible).
• Use common words ("use" instead of "utilize," "start" instead of "initiate").
• Define technical terms the first time you use them.
• Write in second person ("you") and active voice ("Click the button" not "The button should be clicked").
• Avoid qualifiers like "simply," "just," or "easily." If a step were simple, the customer would not be reading the article.

Read your article out loud. If any sentence makes you stumble, rewrite it.

Step 6. Add visuals

Screenshots, annotated images, and short screen recordings make instructions dramatically clearer. A customer who is unsure whether they are clicking the right button will feel confident when they see a screenshot showing the exact button highlighted.

Best practices for knowledge base visuals:

• Capture only the relevant portion of the screen, not the entire desktop.
• Use annotations (arrows, boxes, or highlights) to draw attention to the specific element mentioned in the step.
• Keep screenshots current. Update them whenever the UI changes.
• Use alt text for accessibility.
• If a process involves complex interaction (like drag-and-drop), use a short GIF or video instead of a static image.

Tools like CleanShot X (Mac), ShareX (Windows), or Loom (for video) make capturing and annotating screenshots fast.

Step 7. Add a troubleshooting section

Even in a how-to article, things can go wrong. Anticipate common mistakes and add a brief troubleshooting section at the end.

Example:

Still not working?

• Make sure you are using the correct email credentials. If you recently changed your password, update it in Settings > Email Accounts.
• Check that your email provider allows third-party app access. Some providers disable this by default.
• If you see an error message, search our help center for the exact error text.
• Contact our support team if none of the above steps resolve the issue.

This section catches customers who followed the steps but hit an edge case, preventing a ticket.

Step 8. Review, publish, and track performance

Before publishing, have someone who did not write the article follow the instructions from start to finish. If they get stuck or confused, revise those sections.

After publishing, track:

• Views. High views confirm the topic is relevant.
• Helpfulness ratings. A "Was this helpful?" widget at the bottom of each article gives you direct feedback.
• Related ticket volume. If tickets on this topic decrease after publishing, the article is working.

In TidySupport, knowledge base analytics show you article performance alongside ticket data, making it easy to see the connection between content and deflection.

Knowledge Base Article Templates

How-To Article Template

Title: How to [action] [object]

Introduction: This article explains how to [action] in [product].

Prerequisites: [List anything the reader needs before starting]

Step 1. [Action verb] [task]
[One to two sentences of explanation]
[Screenshot]

Step 2. [Action verb] [task]
[One to two sentences of explanation]
[Screenshot]

Step 3. [Action verb] [task]
[One to two sentences of explanation]
[Screenshot]

Troubleshooting:
- [Common issue 1 and fix]
- [Common issue 2 and fix]

Related articles:
- [Link to related article 1]
- [Link to related article 2]

Troubleshooting Article Template

Title: [Problem description] / What to do when [symptom]

Introduction: If you are experiencing [symptom], this article will help you diagnose and fix the issue.

Symptom: [Describe what the customer sees]

Common causes:
1. [Cause 1]
2. [Cause 2]
3. [Cause 3]

Solution for Cause 1:
[Steps to fix]

Solution for Cause 2:
[Steps to fix]

Solution for Cause 3:
[Steps to fix]

Still need help?
Contact our support team at [support link] with the following information:
- [What to include in the ticket]

FAQ Article Template

Title: Frequently asked questions about [topic]

Q: [Question 1]
A: [One to two paragraph answer]

Q: [Question 2]
A: [One to two paragraph answer]

Q: [Question 3]
A: [One to two paragraph answer]

Related articles:
- [Link to detailed article on subtopic]

Common Mistakes to Avoid

• Writing for yourself instead of the customer. You know your product inside out. Your customers do not. Have a non-expert review every article.
• Skipping screenshots. Text-only instructions are harder to follow and more prone to misinterpretation. Visuals reduce ambiguity.
• Using "just" and "simply." These words imply a task is easy, which is condescending to a customer who is struggling. Remove them.
• Combining multiple topics. One article, one topic. If you need to reference another process, link to a separate article instead of explaining it inline.
• Forgetting to update after product changes. Set up a process to flag knowledge base articles whenever a feature is updated. Outdated instructions destroy trust.

FAQ

How long should a knowledge base article be?

Most knowledge base articles should be 300 to 800 words. How-to guides with multiple steps may reach 1,000 to 1,500 words. If an article exceeds 1,500 words, consider splitting it into two separate articles. The goal is completeness without padding.

Who should write knowledge base articles?

Support agents are the best authors because they understand customer language and common pain points. Product managers and developers can contribute technical accuracy, but the final article should always be reviewed by someone who talks to customers daily.

How do I know if my article is effective?

Track two metrics: the helpfulness rating (thumbs up or down on the article) and whether ticket volume for that topic decreases after publishing. If customers read the article but still open tickets, the article needs improvement.

Should I use video instead of written articles?

Written articles should be your foundation because they are searchable, scannable, and easy to update. Add video as a supplement for complex processes that are hard to explain with text and screenshots alone, like multi-step workflows or drag-and-drop interactions.

How do I handle articles for features that change frequently?

Flag these articles for monthly review. Keep the article structure modular so you can update individual steps without rewriting the entire piece. Some teams add a "Last verified" date at the top so readers know how current the information is.