Knowledge Base Know-How: Common KB Mistakes

If you offer customer support, you have got to have a knowledge base. A beautifully thought-out knowledge base can deflect support tickets and reduce customer wait time. As delightful as your support team is, many customers would rather have the answer right away.

If your team is pounding out the same responses again and again, a KB article can save their butts. Adding a link to a friendly 2-line email is so much nicer than typing the same instructions ad nauseum.


Investing a few hours in an article that will be shared hundreds (or thousands) of times? That’s an obvious win.

Unfortunately, many companies don’t give their knowledge base a second thought. They figure that anybody can write instructions that are clear enough to understand. Alas, it’s much more complicated than that.

Here are some knowledge base tragedies I’ve seen again and again.

1) Skipping steps!

I know this sounds obvious, but skipped steps are a plague. A pox upon users everywhere.

Not the good kind of skipping.

Why do we forget important details when writing for KB? It’s because of a well-known cognitive bias – the curse of knowledge. People have a real problem imagining how others see the world.

Support agents may know your product inside and out, but that can actually hurt their ability to explain simple processes in detail. It’s easy to forget that you have to close a pop-up before you can move on to the next step, or that you must scroll down all the way to find a menu item. For some users, these minute maneuvers become blockers.

Consider the simple instruction: Click Settings

As a user, I have a thousand questions.

  • Is Settings in the top right corner?
  • Or is it somewhere else?!
  • Is it hidden within another menu that I have to click first?
  • Is it represented by a gear icon?
  • Do I have to scroll to reveal it?

All of these details are painfully obvious to someone who already knows where Settings lives.

Here, the missing step  is locating the Settings button.

The solution? Just a few clarifying words to orient the user. Try, “Click Settings, in the top right corner.” 

2) Using only 1 medium.

We all know now that folks learn in different ways. Some prefer to see, some prefer to hear, some prefer to read.

Some prefer 1950’s instructional videos based on discredited science!

Still others prefer to be dutifully walked through on the phone plus a screen share, for an hour and a half. 🙂

At the same time, screenshots might not load, links might get broken, video sound doesn’t come through – for these reasons it’s important not to rely on one mode of communication on your knowledge base.

You should always support media with text. There are a few reasons for this.

  • Text is more easily updated than screenshots and videos.
  • Written words will support TTS (text-to-speech) readers (that’s just good manners.)
  • It serves as a failsafe in case a video link breaks, or if you don’t have time to update it right away.

A good knowledge base is like a good investment portfolio. Diversified.

3) Not reviewing when you release.

There’s nothing worse than an outdated screenshot. Even small design tweaks can throw a wrench in your KB instructions, and cause confusion for your users.

Releasing a new feature? Write the accompanying KB article before the release. Save your users some confusion. At the same  time, give your whole knowledge base a once-over. Related features might need an update, cross-links should be created. If your team does KB review on a regular basis, the process will be painless (I promise.)

If you’re looking to whip your knowledge base into shape right away, a technical writer can come to the rescue. Seriously. Make your life easier! You deserve it. 🙂

Leave a Comment