Writing better Knowledge Base Articles

So often, the problem with knowledge bases is that they are hard to understand. Either the knowledge articles do contain the knowledge and it’s just not communicated that well, or the knowledge base is hard to coordinate. So what do you do? Learn how to write good knowledge base articles here.

What is a good length for a knowledge base article?

No one wants to read a 50 page manual. Make sure your knowledge base articles are as short and to the point as you can make them. A good rule of thumb is that the article should fit “above the fold”. That is to say, you should never have to scroll to read the article.

But be pragmatic. If you need to fit more information, you should. And if everything you need to say is best summarized in three sentences, then let the whole article be three sentences.

Focus on the context of the query in your knowledge base article

We always recommend speaking the language of your end users instead of industry jargon as much as possible. It helps them navigate Self-Service Portals better, and it makes sure they feel like you and them are on the same page. Similarly, it helps them understand your knowledge base articles easier.

The important thing to understand here is you should focus on a solution to the context of the users situation. Not explaining the error codes and how to deal with them. Phrase the problem in a way the user understands “Printer is not working” rather than “printer shows error code 330219”. Bring in technical things like error codes and serial numbers only if you definitely need to.

Make sure your users find the knowledge base articles

And along the same lines – make sure your users can find your knowledge articles. A great thing to do, especially if you have a search functionality in your knowledge base, is to phrase your articles as questions.

This is because people tend to phrase their queries (for example on Google) as questions when they want to find something out. It’s a fun human quirk in how we interact with technology, but one you can put to good use!

Put yourself in the shoes of a user who has the specific problem of what you are writing a knowledge base article for. How would they phrase the question? What keywords would they use? Maybe they would just type “I cannot log in” – then title your knowledge base article just that.

If you have access to search history data in your knowledge base, you can have even have a look and see what the most common phrasings of a certain query are – and how often it crops up.

Consider different levels of experience in solving problems

One good thing to do is to also let your users know what is required from them to solve a problem themselves. A way to do this is to have an indicator at the top of the page that tells the reader how in-depth the procedure is. This could be either a numerical 1-5 type value, or a plain text “intermediate” or “easy”.

These types of indicators are also useful if you need to write a lot of instructions that aren’t actually that complicated. If you reassure people who are faced with a “wall-of-text” that the information is not as complicated as it may look, you can encourage them to actually engage with the text.

Better knowledge sharing in your organization

Want more inspiration on sharing knowledge? Download our Knowledge Management e-book for tips and tricks on knowledge bases, and a way to calculate your time and cost savings.