How to write a knowledge base article

Writing a good knowledge base article is not the same as writing well. Many teams have no shortage of people who can articulate themselves and write great pieces, yet still end up with documentation that is hard to follow, hard to find, and quietly ignored. The difference is almost never talent, but structure, intention, and consistency.

This guide covers what a knowledge base article is, why it matters, how to write one from scratch, and what actually makes knowledge base articles great. If you are still not sure which type of knowledge base you need, start with our guide on internal vs external knowledge bases before coming back here, as this guide focuses more on the actual articles.

What is a knowledge base article?

A knowledge base article is a self-contained document written to answer a specific question, explain a process, or describe how something works. It lives inside a knowledge base; a searchable repository of information, often revolving around a product, service or internal processes. If you're still not quite sure what a knowledge base is, refer back to our article on what a knowledge base is.

How is a knowledge base article different from a blog post?

A blog post is often written to be discovered, to attract an audience, or to make an argument. In a blog post, it is okay to be exploratory, look at things in different ways and not have a definitive conclusion. A knowledge base article, however, is written to be found by someone who already has a problem and needs to solve it. It is not trying to make a case, but to give someone what they came for, as quickly as possible.

This means knowledge base articles are not the place for background storytelling or SEO-driven padding. Just think about the times you've used a food recipe online and had to scroll 5 pages down just to read the ingredient list and instructions. This would be the equivalent if knowledge base articles were treated as blog posts.

Knowledge base articles vs FAQ

FAQs and knowledge base articles are often confused, but they serve different roles. A FAQ is a short list of common questions paired with brief answers, which is useful for quick scanning, but it is limited how in-depth they can go. A knowledge base article, on the other hand, can provide step-by-step instructions, contextual explanation, troubleshooting guidance, and related links.

Knowledge base articles and FAQs are both invaluable tools for building knowledge bases, and they often complement each other: a FAQ may point to a knowledge base article, and a knowledge base article can also include related FAQ in itself.

Who should write the knowledge base articles?

Knowledge base articles are usually written by the people closest to the subject that is covered. This is often, but not excluded to, support agents, engineers, product managers, HR teams or technical writers. Larger teams may have people assigned solely to help write the knowledge base articles, but will often share ownership with someone within the domain of the subject.

More important than who writes a knowledge base article is who own it, as articles without an owner will eventually grow stale and out of sync.

Internal vs external context

As discussed in the introduction to this post, the fundaments of a good knowledge base article applies equally to internal and external knowledge bases, but the writing style and formality of the content shifts a bit. Internal articles can assume shared context and be more direct, while external articles are written for readers who may have no prior knowledge about the service, service or organization at hand, so they require more explanation, clearer navigation and more careful language that takes this into account. For a full breakdown of the difference, see our guide on internal vs external knowledge bases.

Why knowledge base articles matter

A knowledge base is only as useful as the articles inside it. Well-written articles target specific, recurring problems or routines that benefit from being documented. Having this in mind makes sure that things are not documented just for the sake of having documentation, and will help better prioritize which things are documented properly to satisfy employees, customers or other stakeholders.

Some of the most noticeable benefits of having a knowledge base with well-written and structured articles are:

Reduced support load
Improved onboarding (for internal knowledge bases)
Better internal alignment
They enable self-service

Reduced support load

Every question a knowledge base article answers is a support ticket that doesn't get opened, a Slack message that doesn't interrupt someone, or a call that never needs to happen. For customer-facing teams, this is one of the highest-leverage investments available once a product or service grows large.

Improved onboarding

New hires and new users often face the same problem: having a large list of things to learn in a short window of time. A well-organized set of knowledge base articles gives them a place to find answers without interrupting colleagues when they're getting started.

Better internal alignment

When processes are documented properly, there is less ambiguity about how things are actually done. Teams are less likely to drift into inconsistent practices when there is clear documentation on how things are done, and the thoughts that have gone into landing on them. This is especially valuable in fast-growing organizations it is harder to keep on top of communication across the entire board.

Self-service

For external knowledge bases, the goal is for customers to be able to help themselves. For internal ones, it is for team members to unblock themselves without always needing someone else. Both reduce friction and build trust in the documentation system over time, and is a win-win for all parts involved. The support teams can focus on more important things at hand and customers or employees can solve their problems in a short matter of time without external input.

Types of knowledge base articles

Not all knowledge base articles are the same. Before writing anything, it helps to know which kind of article you are writing, because each has a different structure, a different primary goal, and a different reader expectation.

How-to / procedural articles

These articles walk the reader through a specific task step by step. They have a clear start and end point, numbered steps, and usually include a "what you'll need" or prerequisites section. Most knowledge base articles fall into this category, as they best reflect the usual goals of both customers and team members.

Troubleshooting articles

Troubleshooting articles help readers diagnose and fix a problem. They typically start with symptoms and work toward causes and resolutions. The structure is often: symptom → possible cause → steps to resolve. These articles often use conditional logic ("if X, try Y; if that doesn't work, try Z").

Reference articles

These document facts, specifications, or configuration options that readers look up rather than follow. They don't guide the reader through a process — they provide the information needed to make decisions or complete work elsewhere. API docs, glossaries, and settings references are common examples.

Policy articles

Policy articles define rules, expectations, and the scope of those rules. They answer "what is the policy" rather than "how do I do something." A good policy article states who the policy applies to, what the rule is, and what to do if an exception is needed.

Concept / explanation articles

Concept articles explain how something works without assuming the reader needs to do anything specific. They build understanding that supports other tasks. These articles are common in technical documentation and are often the bridge between a new user and more specific how-to content.

Knowing which type you are writing before you start makes the structure easier to define and the result more consistent with the rest of your knowledge base.

What makes a good knowledge base article?

Good knowledge base articles share a few qualities that have less to do with writing skill and more to do with intentional design. These qualities include:

A clear, searchable title
Step-by-step formatting for procedural content
A scannable structure
Screenshots and visuals
Tags and metadata
A named owner and a review date

A clear, searchable title

The title should match the language the reader would actually use when searching. "How to reset your password" is better than "Authentication recovery options." Boring, predictable titles are a feature and makes searching a lot easier (also AI agents).

For more on this, see our guide on how to structure a knowledge base.

Step-by-step formatting for procedural content

Numbered steps are not just a stylistic preference, but can also help readers keep track of where they are, make it obvious when a step has been missed, and make it easier to resume after an interruption.

A scannable structure

Most readers do not read knowledge base articles top to bottom. They scan for the section that answers their specific question. Headers, short paragraphs, and clear labeling serve this reality rather than fighting it. This also emphasizes the importance of keeping knowledge base articles atomic and focused to specific problems, so that they are easy to digest and navigate.

Screenshots and visuals

A screenshot showing exactly where a button is located can prevent confusion faster than a paragraph of description. Leaning into what we previously discussed about scannability, visuals greatly improve how fast users can navigate and consume content, but it comes with a caveat: visuals easily go stale.

As products change, screenshots will have to be updated accordingly, which is a tedious task. Use screenshots and other visual aid where they genuinely reduce ambiguity, but not as a default. Additionally, when visuals are included, they should supplement clear writing (and accompanying alt/image descriptions for sight-impaired users.

Tags and metadata

Categories and tags make articles discoverable beyond the main navigation. An article on password resets might live under "Account settings" but should also be tagged with "login," "access," and "credentials" so it surfaces in a variety of search scenarios.

A named owner and a review date

This is less about writing quality and more about trustworthiness over time. An article with a named owner and a visible review date signals to readers that someone is accountable for its accuracy.

How to write a knowledge base article (step-by-step)

1. Identify the problem

A lot of the work in writing a good knowledge base article starts before even putting pen to paper (or fingers to keyboard). One of these steps is to identify the problem at hand, as articles in a knowledge base should address existing problems, not invent them. Every knowledge base article exists because someone, somewhere, has a specific problem or gap in knowledge. Before writing anything, write down the problem the article will solve in a single sentence: "A user cannot find where to update their billing information" or "New hires don't know how to request time off."

The problem statement keeps the article focused. If you cannot write the problem in one sentence, the scope may be too broad and should be split into multiple articles.

2. Define the audience

Who is this article for? A new customer who has never used the product, or an experienced user troubleshooting an edge case? An external user unfamiliar with your internal terms, or a team member who needs a quick refresher on a process they already know?

The answer changes what you can assume the reader already knows, and also touches upon what type of knowledge base is actually at hand. For internal audiences, like within a team or organization, there's usually talk about an internal knowledge base, and for articles that should be accessible to the public, like customers or prospect clients, an external knowledge base is more appropriate.

3. Choose the right article type

Based on the problem and the audience, decide which article type fits best. Is the reader trying to do something (how-to)? Diagnose something (troubleshooting)? Look something up (reference)? Understand something (concept)? Matching the structure to the task makes the article easier to write and easier to use.

4. Create a clear structure

Before writing the body content of the article, roughly sketch out the structure. For how-to articles, this is usually a brief intro, prerequisites, numbered steps, expected outcome, and a troubleshooting section. For troubleshooting articles: symptoms, causes, resolution steps, escalation path.

Keeping a repository of templates for common articles can make this step a lot easier, as they reduce the blank-page problem and make the result more consistent across the entire knowledge base.

5. Write in simple, direct language

Using plain language with short sentences makes articles more accessible to a broader target audience. It's a good idea to provide definitions for technical terms or jargon the first time it appears, so that less knowledgable users can still feel in-the-loop.

6. Add visuals

Add screenshots or diagrams where they reduce ambiguity, particularly at steps where the reader needs to find something specific in a UI, or where the written description is hard to follow without seeing it. Add supportive captions and alt text to the added visuals.

Keep in mind that visuals are more likely to getting out of sync, so do keep usage light and only in the most important places.

7. Add metadata and tags

Once the article is written, assign it to the right category in your knowledge base hierarchy and add relevant tags. Tags enable discovery beyond the main navigation and help AI-powered search surfaces articles across related queries. Think about the different ways someone might search for this content and tag accordingly.

8. Review and publish

Before publishing, it's good to have a small checklist to ensure your article satisfies requirements such as:

Does the title match how someone would actually search for this?
Does the article do one specific thing?
Are the steps accurate and in the right order?
Does the article assume knowledge the target reader doesn't have?
Is there a named owner?

You can create and share your own internal checklist as an additional quality pass when people contribute to the knowledge base.

9. Maintain and update

Publishing an article to the knowledge base is not the end, and the actual hard part actually starts from here on out. Knowledge base articles become wrong over time as products, processes, and policies change, and keeping them updated is a practice in itself. Assigning ownership before publishing and integrating maintenance into existing workflows are essential steps in ensuring that articles don't go stale and out of sync. For a full approach to this, see our guide on how to maintain a knowledge base.

Knowledge base article format (with example structure)

The format of a knowledge base article is not universal and is usually dictated by the article type. But most procedural and troubleshooting articles benefit from a consistent structure. Below is a format that works reliably across most knowledge base types.

Title

A short, specific, searchable title. Use "How to…" for procedural articles, and "Troubleshooting…" for troubleshooting articles.

Summary

One to three sentences describing what the article covers and who it is for. This helps readers confirm they are in the right place before reading further.

Applies to

The product, version, user role, or context this article is relevant to. Especially useful in larger knowledge bases where articles may have different applicability.

Prerequisites

What the reader needs to have, know, or have completed before starting. Permissions, prior steps, software versions, and so on.

Steps

Numbered steps for procedural content. Each step should be a single action. Include screenshots where they reduce ambiguity.

Troubleshooting

What to do if something in the steps doesn't work as expected. Common error messages, conditional paths, and escalation guidance.

Links to related content that the reader might need next, or that provide useful additional context. Internal linking improves discoverability and keeps readers from dead ends.

Common mistakes to avoid

Writing like it's marketing

Knowledge base articles are not the place for brand voice, warm introductions, or product enthusiasm. Readers are there to solve a problem.

Not updating content when things change.

An outdated knowledge base article is worse than no article at all, because readers trust it and act on it, leading to frustration when things don't work out as expected. Every article needs an owner and a review process that is connected to how work actually happens in a team or organization.

No ownership

An article without a named owner will quickly go stale, as responsibility fades without direct ownership. Being put as the owner of an article does not mean that that person has to do all the work, but that they are responsible that the accuracy of that page.

No cross-linking

One of the biggest advantages of a knowledge base is being able to interconnect and link between related articles and resources. Knowledge base articles should not live in isolation, as readers often need related information when gathering context about their problems or goals.