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.

• 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.

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!

• 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