How to Write a Knowledge Base Article: 9 Easy Steps

Have you ever come across a knowledge base article you couldn’t make heads or tails of? If so, you’ll know that low-quality help content damages the customer experience.

Conversely, well-written knowledge base content is a tried-and-true way to reduce reliance on live agents and help customers get the information they need, instantly.

Let's get started.

What is a knowledge base article?

A knowledge base article is a type of help doc that is designed to either answer frequently asked questions or aid customers with solving problems they commonly run into.

Despite the name, knowledge base articles don't have to be limited to writing, and may also use videos, images, and other media if it helps get the point across.

Types of knowledge base articles

There are a few different types of knowledge base articles you might come across. Some common examples are:

• Questions and answers (FAQs)
• Installation, how-tos, step-by-step guides
• Troubleshooting
• Product descriptions

Each one of them demands its own unique structure and approach.

9 steps to create a knowledge base article

1. Think of the audience

One rule of thumb is to assume your readers know nothing, so everything needs to be spelled out and explained. This doesn’t mean you fill articles with extraneous information. If you’re writing an article about how to train a chatbot, you can assume your readers know what a chatbot is. But, while writing about the training process itself, you need to describe the concepts used and steps readers take thoroughly as if they are seeing them for the very first time.

Knowledge base article "Do"

• Go to your account and click on "System Preferences", then "Set key".
• You can train a chatbot by using the tool “Smart suggestions” in chatbot settings.

Knowledge base article "Don't"

• Go to your account and set up a key.
• You can train your chatbot via the chatbot settings.

If explanations unduly increase the length of an article, or over complicate it, use links instead: write a separate smaller article and point the user to that via a clear anchor text.

2. Decide on the type of article

Depending on which article you want to write, you’ll have an initial plan and timeline, and a particular approach to your preparation efforts (see next section). 

The type of article will also affect your structure. Installation and user guides have a strict chronological order, while FAQs may cover anything from the easiest-to-understand concept to the more advanced.

3. Gather knowledge before writing

Clarity of writing comes from clarity of thought. 

Before you start writing:

• Walk in your customers’ shoes. Go through the sequences, jot down steps, and make a note of anything tricky that may require further explanation. Screenshots help, too.

• Look into operations. Talk with your colleagues and go through tickets in your support software or records in live chat or chatbot conversations to collect the most common customer issues (and the correct answers). Listen to customers directly either on social media or by speaking to them, if you can.

• Get knowledge. If you’re called on to write a semi-technical knowledge base article (e.g. a user guide), it’s a good idea to ask for relevant documentation or even consult directly with internal experts.

• Use analytics. A data-driven approach works for every type of knowledge base article. For example, you can use Google Analytics to discover the terms users type in your Knowledge Base search field, compare that to the content you already have, and identify gaps.

4. Start from the reason

Begin every knowledge base article by stating the reason you’re writing it – which should match the reason your customers are searching for it. “Reset your password” articles could start with “If you’ve forgotten your password or get the ‘password isn’t correct message’ follow the instructions below to set a new one.”

This will help:

• You, to begin unraveling the solution to the problem and write an effective article
• Your customers, to make sure they’ve landed on the right content and understand what’s happening

5. Allude to the benefits

Knowledge base articles don’t have to be purely utilitarian. If your knowledge base is publicly available online, your knowledge base articles may end up ranking on search engines and getting clicked on by people who aren’t your customers (yet).

There’s no downside to mentioning the benefits for the customer of each product or service you’re describing. Even technical knowledge base articles, like articles explaining the nuts and bolts of SLAs, can have a hint of why SLAs are important to your company and customers.

6. Make your content easy to skim

A knowledge base article should allow readers to scan the most important points at a single glance. 

That’s because a user might have followed a process correctly but stumbled at one particular point. You want them to be able to find the solution without having to go back over all the information.

It also helps content display properly on mobile, promoting a positive experience across devices.

Here are some key elements to consider:

• Headings. Headings help readers easily spot the parts that interest them the most. 
• Bullet points. Bullets break up the text and stand out better so are easier to remember.
• Text formatting. Use bold for commands or buttons, and italics when quoting the messages users see on their screens.
• Symbols. The “>” symbol is especially useful in demonstrating a series of clicks in a single step. 

7. Mind your language

Your choice of words and turn of phrase can make or break an article. 

So, when writing a knowledge base article, here are some rules to remember:

• Grammatical mistakes are a no-no. If you’re not sure you’ve got it right, ask a second pair of eyes to check.
• Proofread relentlessly. Typos are off putting. Your readers will respect your content less (consciously or subconsciously) if your articles have multiple mistakes.
• Be serious, but conversational. Try to write like you’d speak to a customer: avoid passive voice when possible, use “you”, and steer clear of idioms and complex phrases. 
• Go easy on the technical. Try to avoid technical terms unless they are absolutely necessary. When you do use them, explain them briefly inside parentheses or link to other articles that explain them.

8. Choose informative titles 

Imaginative titles will confuse readers and make knowledge base articles difficult to find. Instead, choose titles that accurately describe the content of the article. Here are some common phrases used in titles of knowledge base articles:

• Getting started with…
• How to set up…
• What is… 
• How to use…

The correct title might be tricky for more complex topics. For example, whether you choose “How our API works” instead of “How to integrate your existing software” depends on what you know about your customers and their queries.

An idea that helps is good ol’ keyword research. Whether via Google Analytics or via an SEO tool like SEMRush or Moz, you can find what users are actually searching for regarding a particular topic.

9. Show don’t tell

It’s fair to say that any person who has tried to navigate software using an article without any visuals has had issues. 

So, consider adding these visuals to a knowledge base article when appropriate:

• Screenshots. With tools like Lightshot and Skitch, you can even draw on your screenshots to highlight specific areas.
• Videos. If you don’t have the resources for full-blown professionally developed videos, a Loom or Camtasia recording is much better than nothing.
• Other formatting that stands out. If you really want customers to take notice of something, use various types of formatting, such as colored backgrounds.

Knowledge base article template

To help you get to grips with writing your knowledge base articles, we’ve created a set of handy templates. You’ll find a range of templates broken down by article type as well as an explanation on how to use them.

A knowledge base article to to be proud of

Make sure you give your customers every chance to get to grips with your knowledge base articles. For example, a customer service agent can link to them directly from live chat and you can also fit them seamlessly into chatbot interactions to create comprehensive 24/7 self-service support.

And remember: don’t get complacent; gather feedback (e.g. via CSAT surveys that pop up in your knowledge base), adjust and refine. After all, your knowledge base works only if your customers think it does.

KNOWLEDGE BASE SOFTWARE

Easily build knowledge bases that have all the answers

Do you have any other tips for writing knowledge base articles? Let us know in the comments.

Benedict Clark

Content Editor

Benedict Clark is a psychologist, writer, and former digital marketer. He writes about the interplay between customer experience and psychology for Acquire.