How to write a helpful knowledge base article

A knowledge base is an important part of your company’s self-service strategy, or your internal knowledge management efforts. A knowledge base is a set of organized information relating to your products and services, that users can use to learn more or find answers to common problems.

The right knowledge base software can help you create visually compelling articles that help your users. But it’s not so easy to write the content. That takes time, effort and skill. In this article, we look at 8 actionable tips to enable you to write helpful knowledge base articles.

Whether you already have a knowledge base or are looking to set one up, there are steps you can take to write better knowledge base content right now. 

1. Ask the right questions

This first step is laying the foundation for a helpful knowledge base article. If you don’t ask the right questions, your article will lack direction and end up being a confused mess. You need to identify your audience’s needs and how your information will help them. 

Do your customers currently face any problems that you could help them overcome? This could inform the next topic for your knowledge base. Your aim should be to help users find the answers they seek about your product or service. 

Here are 5 questions to ask that will enable you to write a helpful knowledge base article: 

1. What is your article’s goal? 

2. What expectations and needs does your audience have? 

3. What processes do users currently have?

4. What is the current experience of your audience?

5. What will strike a chord with your audience? 

Answering these questions will help you better identify your audience’s needs. 

2. Avoid making assumptions

Users are coming to your knowledge base to find answers to their questions, so your next goal is to make your content impossible to misunderstand. 

When you write your knowledge base articles, imagine that your audience are complete novices. Don’t use complex terminology or jargon, and avoid casually mentioning to-dos in passing. Do assume that users will need guiding through every step. 

For example, if a customer is creating a new category or article within their knowledge base, which step is more helpful? 

1. Create a new category or article. 

2. Create a new category or article (or edit an existing one by clicking on the wrench icon to the right of any content) inside Knowledge Base > Articles.

Option 1 assumes the reader has all the information they need to create a new category or article. The second option includes both customers who know how to add content as well as those who don’t. The second one doesn’t make assumptions about what the readers know, and breaks the documentation down into easy to follow instructions. 

You sabotage yourself when you make assumptions about what constitutes “simple” instructions. You’re more successful when you over-share, since more experienced users can skim past the information they don’t need, while beginners will run into issues when you leave out important details. 

3. Write in plain language

It’s a huge turn-off for your users when they come across content they don’t understand. No one wants to feel like they aren’t intelligent, and making your users feel that way is a surefire path towards unhelpful documentation. 

Write in simple, plain language as much as possible so your users can understand even the most complex of concepts. It sounds easy, but you know all sorts of jargon and acronyms that are likely to mystify your users. 

If you’re writing for customers, don’t assume that they know anything about your product. Avoid using technical or industry buzzwords that you’re likely to use every day inside your office. 

Keep sentences simple and easy to read. Use tools like Hemingway to check that your language is as clear as possible. 

4. Use a table of contents in longer articles

Sometimes you might have to write very long knowledge base articles in order to explain every step in a process. In this case, it’s helpful to include a table of contents with anchor links to the rest of your article. 

Here’s an example of an article with a table of conte

When you need to write a longer knowledge base article, a table of contents makes it easier for more experienced users to quickly jump to the section they’re looking for. 

Even if an article is on the shorter side, a table of contents still makes it easier for users to find the information they’re looking for. 

5. Use headings to break up text

When you’ve written your article, it’s time to make sure the content is structured properly. You should make use of H2 and H3 headings throughout your article to break up the text and ensure readers can scan the article for the information they need. 

Here’s an example of an article using subheadings: 

It’s a natural tendency to scan the headings of an article to make sure it’s worth reading the whole thing. Creating headings for each section enables users to save time by helping them find the content they really need. 

When it comes to making content skimmable, you can also use other formatting options such as callouts, bullet points and numbered lists. This helps to pull out important information from the surrounding content and also breaks up long walls of text. 

6. Structure your article logically

A knowledge base article is more helpful when it’s structured around the user’s workflow. If you don’t know how to structure your article, then it’s unlikely your users will be able to understand what you’re telling them to do. 

Unless you want users to be confused by your content and give up in favor of calling support, follow these principles to structure your article: 

• Chronological order: You should organize your knowledge base article into the chronological order of steps. The first thing you ask users to do should be step one. 

• Order by difficulty: If there is no chronological order to the steps your users should take, then instruct them to perform the easiest task first. If your users start off with early difficulty, this decreases the chance they will stick with your article to the end, so start with the quick wins. 

• Think about the workflow: If you interrupt your users in the middle of a task, they’ll get distracted and lose momentum. Don’t interrupt a workflow until the user is at the end. 

If you have extra information you think would be helpful to your users, add in a list of follow-up questions at the end of the article. 

7. Choose simple article titles

Titles are the first thing users see when browsing your knowledge base content. They should be kept as simple and straightforward as possible so users understand exactly what is contained in the body of the article. 

When thinking of article titles, ask yourself: What is my user going to search for? 

People tend to search your knowledge base using basic keywords. “How to upload a file” tends to shorten to “upload file”. You can add extra search terms to the article as tags to ensure it’s pulled up during the user’s search. 

You should avoid being creative and exciting with your titles. Instead, use action words in the active voice to structure your titles. Here are some examples: 

• “How to ___”

• “Using ___”

• “Setting up ___”

8. Include relevant images

A picture is worth a thousand words. As long as you outline your instructions clearly, you can also include screenshots or GIFs to accompany your written documentation. 

You can write fewer words and make your instructions clearer by including relevant images. They can be used to show each step in your interface, and you can also annotate them with numbers or arrows. 

Every step explaining how an action is performed can be followed by a screenshot showing exactly what the step would look like in the interface. 

Consider using Snagit as a screenshot tool, which is a simple feature-rich tool for screenshotting that works on both Mac and Windows. Remember though – screenshots are likely to need updating in the future. 

Final remarks

There you have it – 8 simple ways to make your knowledge base articles more helpful. Your users will be delighted with your content and be more successful with your products and services because you have put in the effort behind the scenes. 

From asking the right questions, to structuring your article effectively, to adding relevant images, your knowledge base content will stand out from the crowd. If you remember nothing else, remember that great help content is designed with users in mind.