How to Write a Knowledge Base Article in 6 Easy Steps

10 min read

So, you’ve been tasked with writing a knowledge base (kb) article for your company, now what? It might seem like an intimidating task at first, but it doesn’t need to be too hard at all. With this blog, we will cover everything you need to do to write a kb article in just 6 easy steps.

What is a kb article and why do I need to write one?

But first, let’s talk about what exactly a kb article is and why you might need to write one. Kb articles are a pretty wide term that covers essentially all product-related information that a customer might need to be successful with your product or service. This might include:

  • How-to guides
  • Troubleshooting information
  • Getting started and setup articles
  • New feature announcements
  • FAQs
  • And much more

The reason you might need to write a kb article is if your company sells products or services that aren’t 100% self-explanatory. Which, with today’s technology advancements, are most companies.

For example, if you’re selling a banana, you don't need to write a user guide on how to peel and eat it because most, hopefully all, people already understand this. But, when selling a more complex product, or anything that involves setup information, you’re going to need to teach your customers how to best use and succeed with your product. For example, if you sell security cameras, your customers need to know how to set them up, connect them to their phone, download the videos, and much more. That is where a knowledge base comes in.

Now, let’s talk all about how to write an educational and successful kb article.

Step 1: Gather your info

Before tackling any writing, you first need to figure out what it is you are writing about. Is this kb article about setting up, is it troubleshooting a common problem, are you covering everything in one?

So, make sure you understand the exact process you need to cover in the article. For example, if this blog were a kb article, the “process” we are covering is writing a kb article.

Whatever you choose should be specific enough that a customer can find the info without reading a 100-page novel, but broad and common enough that it will help many customers. For example, this article isn’t about writing an article nor is it about how to write a kb article on connecting security camera devices to an iPhone. Balance is key.

After you’ve nailed down what exactly the kb article will be about, it’s time to do your research. If you’re going to write about connecting a camera to Bluetooth, you need to understand exactly how to do so. If you can’t understand it, then your readers won’t be able to either. This means rolling your sleeves up and diving into the product or service yourself to fully understand all of the nitty-gritty details.

After you’ve sufficiently gathered all of the information, it’s time to get inside your audience's head.

Step 2: Get inside your audience’s head

Now that you understand exactly how to use the product, you have to take a step back and pretend to forget everything you’ve just learned. Now I know, this may seem counterintuitive, however, it is absolutely critical in writing a successful kb article.

In order to properly educate customers, you have to speak a language they understand. And you have to bring yourself back to a beginner’s level. Try these three simple steps:

  1. Start over. First, imagine you are brand new to this product or service and have zero knowledge of how it works. If you’re being tasked to write a kb article for an advanced, non-beginner audience, then imagine what level of knowledge they might contain versus what they do not yet know.
  2. Ask questions. Now, think about all of the questions you might have about the process you are writing about. If your article is about connecting a camera to Bluetooth, you might ask yourself, do I even know how to turn on the Bluetooth settings on my phone? While that may not seem related to the camera your company sells, it is a critical step in informing your customers on how to succeed. The last thing you want is to make them conduct additional research on the steps you didn’t cover in your article. Oftentimes, these types of things can be overlooked.
  3. Assume nothing. The biggest key when climbing inside your audience’s head to write any kb article is to assume your audience knows nothing. Assuming they know more than they actually do is the worst mistake you can make because it will leave the reader feeling frustrated and confused. With every sentence you write, ask yourself, would an absolute beginner understand this?

Now that you understand who your audience is, what they know, and what they need to learn, it’s time to start drafting out the actual structure for your article.

Step 3: Plan your kb article structure

Finally, time to get into the actual article! The best way to tackle writing anything is to start with a solid plan. If you can get your article structure together, the writing will be a breeze.

But how do I build a kb article outline?

  1. List topics. First, list out all of the questions that your article needs to answer (the ones we thought about in step two). Some kb articles might be very to-the-point and only discuss technical steps, while some like to talk about the advantages of a feature, benefits, ideas, and more. It all depends on your [brand’s voice].
  2. Arrange topics. Now, try to make sense of these topic points by putting them in an order that flows well. As a whole, you will start with an introduction, discuss what the article will be about, dive into the most common information first, then get more advanced as you progress. Here’s an example:
  3. Add a table of contents. If your kb article is going to discuss more than a couple of topics (like our example above) then it can be a huge help to add in a table of contents at the top that will link throughout your article. This way, customers can easily find the specific answers they need without scanning through your whole page.
  4. Plan content. Now that you have all of your headers put together, it’s time to list out what you would like to discuss in each. Try adding a few bullet points on the topics you’d like to hit, so when it comes time to write, you already know exactly what to say.
  5. Plan visuals. Finally, start thinking about images. What parts of your guide will need further visual explanations? Do you need to create images or can you take screenshots? If you’re creating images, start a list of the ones you will need.

Step 4: Turn your notes into engaging writing

Yes, actually writing the article isn’t until the fourth step. But for good reason. Now, you understand your audience, thoroughly know what you need to explain, and have your entire article and necessary talking points planned out. Because we’re so prepared, writing will be a breeze.

However, there are still some important things you should keep in mind when transforming your notes into actual copy that customers will understand.

  • Use simple step-by-step numbered or bulleted lists whenever possible. This is a huge must-do for improving visibility and ensuring audiences can easily scan your document to find the necessary information they need. Customers prefer to read a few simple steps over a long, intimidating paragraph.
  • Keep paragraphs short. Break them up as much as possible with additional headers, lists, or images. Long bodies of text can look very intimidating and might cause a customer to give up on finding their answer. People like quick information in today’s world and don’t have the time to sit down for hours to read for answers.
  • Highlight the important information. If you have any important warnings, tips, ideas, or tricks inside your kb article that you want people to easily find, make sure it stands out in your text. You can highlight them in different colors, underline, bold, or whatever works with your brand style.
Highlight important information in kb article
  • Avoid jargon! As we discussed in the beginning, it’s best to assume your readers are complete beginners. Therefore, they are not going to understand any complex and technical language surrounding your product. Keep your language simple, easy-to-read, and human. And when you can, try to introduce some personality. Depending on your brand’s voice and tone, you could even add some light humor, quirky sentences, and relatable narration. But remember, the true purpose of the kb article is educational. So don’t let your important information drown in long personal stories or distracting jokes. Read some of our tips on crafting great copy.

Step 5: Add visuals

Now, for the fun part! Most of your customers are probably visual learners and will understand your kb article better if they can visually see what you are talking about. Unlike a blog post, kb article images are used for educational purposes, not flare.

Examples of media you might include in a kb article:

  • Screenshots of the process you are discussing (if it is an online one, of course)
  • Product or part images
  • GIFs walking the user through a few simple steps
  • Instructional videos
  • Demonstration videos

For each of these, a little editing can go a long way. Let’s say you are discussing the three steps to turning Bluetooth on from your iPhone. If step number two is to click on the “Bluetooth” button under the settings app, then in your screenshot, you could add a small red circle or arrow highlighting where this button is on screen. Sometimes when customers are unfamiliar with a new process, these types of callouts can help them find their answers quickly and easily.

Example of how to make visuals helpful in your kb article

But, how do I decide where I need to add visuals?

The best rule of thumb here is to add them to every place that makes sense. When it comes to visuals, the more the merrier, as long as they are useful and informative. If you want to include a screenshot of every single step a user must take, great. I’m sure many customers will find this useful. However, stray away from adding in a photo of your dog. While it may be adorable, your customers are just looking for answers right now.

If you’d rather stick to minimum images, read through your article, pick a couple of complex areas that could really use further information, and start there.

Step 6: Link to your other kb articles

Good news, the final step is the easiest one! Now that you’ve got a completed article filled with visuals and carefully-crafted information, the last thing to do is ensure customers can find all of your other content in case they come up with more questions while reading.

  • First, scan through your text and find areas where you discuss any topics that are mentioned in your other kb articles. If you don’t have any others, this is a great opportunity to jot down some ideas of more complex items you could expand more on in a future article.
  • Try to keep an eye out for product names and features. Maybe you mention the camera’s instant download feature and happen to have an entire article on how to use it. Go ahead and link it!
servicetarget kb article example of linking to other guides
[This example comes from a ServiceTarget KB article]
  • Search for potentially confusing areas that you could link to external resources for. Maybe you don’t want to get into the nitty-gritty of iPhone’s Bluetooth capabilities but want to make sure your customers can learn if they need to. Go ahead and link out to one of iPhone’s articles, this way, your customer can find their information in just a click.
  • Finally, end your kb article with related articles. Maybe the next natural step for your customer after connecting their Bluetooth is to download your app. If that’s the case, go ahead and link to your kb article on setting up the app. This way, your customers don’t need to search for their next question because it’s already been answered.

Take-aways

If you take anything away from this blog, let it be this: Kb articles are not as hard as they seem. Don’t be intimidated by the complex details and tech language, because jargon is actually the opposite of what you should be writing. Keep it simple, stick to the facts, and your customers will be pleased.

Now, keep learning more about knowledge base articles with our blogs on elements of a great kb article plus examples, why your customers need kb articles, and Planning a brand new technical documentation kb from scratch - everything you need to know

David Hayden
Software entrepreneur who enjoys building products that empower business people to create and evolve enterprise applications without code.

Want to learn more about what we offer?

Explore the stages of our product tour and the self-service solutions we provide to see how our diverse applications can work for you.

Explore more blog posts!

That's not all! Our blog has tons to offer. Explore more posts below to keep learning!

knowledge base content planning

How To Select the Best Knowledge Management System for You

Knowledge Management

There is a lot to consider when evaluating and selecting the best system for your needs. In this blog, we will cover where to search for solutions and what to include on your shopping checklist.

continue reading →
customer service team

12 Top Customer Service Challenges and Ways to Overcome Them

Customer Experience

Customer service is one of the most important aspects of any business. It can make or break a company. In this article, we outline the 12 top customer service challenges and discuss ways to overcome them.

continue reading →
knowledge management system

Knowledge management systems: how to choose the right one

Knowledge Management

Knowledge Management is crucial for any organization today. With more and more teams choosing remote or blended working options and the sheer amount of information that is being created and shared on a daily basis, it's more important than ever to have a system in place to manage and share knowledge effectively. In this article, we share essential knowledge management system features to look for to make the process of selecting and adopting KMS an easy one for you.

continue reading →
document search

Search Relevance: What It Is and How to Build a Relevant Site Search

Customer Self-Service

Users expect a lot from website searches nowadays--they want lightning-fast, personalized, and most importantly, relevant results. However, creating a relevant search can be a complex process. Many websites struggle to provide optimized results pages that match users' intent and bring them to their needs with ease. In this post, you’ll learn how to increase the relevance of your website search using travel time data.

continue reading →
enterprise search

Enterprise Search Best Practices

Knowledge Management

The search function is one of the most crucial aspects of any Knowledge Management project. A well-designed search experience enables both your customers and employees to more quickly access the most relevant, personalized information when and where they need it. Find out how you can provide an effective and efficient enterprise search experience by following some of the best practices we outline in this article.

continue reading →