How to Write an Effective Knowledge Base Article

Sometimes the best support means getting out of your customer’s way.

A knowledge base can be a customer’s best friend during the “help me help myself” phase of exploring your product. But as Kathy Sierra shares in Making Users Awesome, companies often drop the ball with post-purchase publishing. Help content is usually one of the first things to feel the sting of mediocrity.

Docs can put the beauty back into documentation, but clean, organized writing doesn’t come in the same turn-key fashion; it’ll take sincere effort.

You need to be informative, engaging, unquestionably clear, and mindful of how and why a customer searched for help in the first place. Here are a few tips for doing exactly that.

Don’t make assumptions in your article

Customers check your docs to solve problems. Your most important goal is to be impossible to misunderstand.

While expertise operates on a spectrum, you should write as if the customer is a beginning user of your product. Skip the advanced terminologies and jargon, and be wary of mentioning to-dos in passing; customers are likely to hit roadblocks there. It’s safer to assume that they’ll need guidance for each step.

An example:

If a customer is looking up how to migrate their website to a new host, which one of the following leaves the least room for error?

  1. Before you continue, make sure to change your IP address.
  2. Before continuing, change your IP address by going to Settings > Manage Domain > IP Address.

The latter. Don’t self-sabotage by making assumptions about “simple” instructions. It’s better to over-communicate.

Make the content easy to browse

Don’t bog down or intimidate readers with a wall of text—when solutions aren’t easy to find, contacting support will be the customer’s next step. That’s a failure to communicate and a frustration for both of you.

Designer Rafal Tomal shows below how proper use of sub-headings and line breaks are a shortcut to an easily scannable doc.

Read More

No Comments Yet.

Leave a comment