Writing a knowledge base article is a surprisingly difficult task.
How can you keep the language simple and clear? How do you get across the information without making your customers fall asleep? 😴
Good news is you don't need to take a class in technical writing. In fact, the less you know about the subject the better.
Ironically, many knowledge base articles are more complicated than the product itself. This leads to baffled customers and no reduction in support ticket volume—silly, right?
It seems as though this complicated, technical writing routine has remained from the era of reading a heavy manual. But the world has moved on since then and documentation has shifted online.
Here's a list of things you can do to make sure you don't confused your customers and instead give them the right answer without all the fluffy extras they don't need.
1. Choose the right headings for your articles
Want a knowledge base that's easy to read and sort?
Make sure your article headings make sense. Your customers need to find the right article and in good time too.
The first mistake I often see is sticking 'How to' at the start of every article. To be fair, it's an easy one to make and I've been a culprit in the past.
Your customers are on your knowledge base to find out how to, so there's really no need to add it in there. It just makes it more confusing and compromises the search results.
If you feel the urge to write it every time, you might be better off going with first-person headings (e.g. How do I connect my Slack integration). This way, your heading will be varied and easier to search. Selma's knowledge base is a great example of this in action.
Plus, it's a extra friendly approach for customer queries.
2. Use a short & sweet introduction
Let's be honest—your customers aren't on your knowledge base for fun. They're just trying to find an answer for themselves without having to contact a human because, well, they're pretty terrifying.
When writing the introduction to your article, make it as short as you can. Like, two paragraphs max. Brevity is your friend and also your customers'.
There's only two things that are useful mentioning in the introduction:
- What the article will solve for the customer
- Why they should care about solving it
Get to the point as soon as possible, because people tend to be lazy and a block of text doesn't look super appealing.
Think of it as the jam on a Victoria Sponge Cake—too much is sickly, but just a small amount is delicious. 👌
3. Make the content easy to read & understand
A knowledge base article should be easily skimmed and understood. Don't go thinking your customers will read every word you write. No, no.
This means you have to magically turn something difficult into something digestible, simple, and readable at every education level—whether they're in elementary school or university.
There's a couple ways to make it easy to digest.
Use plenty of imagery and GIFs
As they say, a picture is worth a thousand words and littering your content with visual examples makes it oh-so-easy for customers to understand.
This is extra helpful if you're selling software. Inevitably things get buried in menus and not-so-obvious places, so it's best take a quick screenshot or two for clarity.
Lists are your friend
Breaking down content into lists for your customers is one of the best things you can do for readability. Being able to quickly skim and follow actions saves them a chunk of time.
When a customer has to go through a process like, say, returning an order or changing their password, a set of steps means they get the thing done right first time and they don't have to get in touch. A win-win.
Highlight the important stuff
Whether it's a warning, quick note, or a casual comment—there's some stuff you'll want to make sure people read. This is where a callout comes in handy.
Callouts stand out from the crowd of your content—making sure customers read the information in them. Use these to surface important information.
4. Keep your knowledge base updated
It's easy to set and forget a knowledge base. But as your product changes, your help centre has to play catch-up.
Without up-to-date information, you'll waste time and money as an influx of customers get in contact after getting stuck following your past guidance. We think it's so important, we built a feature to remind our customers.
Keeping everything neat and tidy can seem like a chore, but it's far easier to do a little housekeep on some content than deal with hundreds—maybe even thousands—of people asking the same questions.
It's a great idea to keep checking the feedback analytics to see how customers are responding to certain articles. Read the article and see whether the wording was unclear or if the feature could be improved.
Rather than leaving your knowledge base to gather dust, think about bringing it up at monthly or quarterly company meetings. A quick check with your engineering, support, and product team will likely save a ton of tickets down the line.
5. Understand your voice & tone
When you're starting to write documentation, it can be tough to keep a consistent style and tone—particularly if there's more than one contributor.
And having more than one contributor is great. Try to get teammates who work in areas to write about each area. For example, ask your hiring manager to write content on the hiring process.
Whoever's writing, here's some general tips to keep your content in check:
- Make sure humor doesn't detract from instructions. Remember, the customer is there to get an answer, not a laugh
- Don't write your article like a blog post. Keep it short and to the point.
- Write like you'd respond to a customer support ticket. If you use informal language like us, do so in your docs. If you don't, use a formal style. This'll keep the support experience consistent.
- Don't conclude your articles. Knowledge bases aren't blogs, so there is no need to add a conclusion. Chances are your customers won't read it anyway.
Whatever style you choose, make sure the whole team understands what tone you're looking for.
If you look after your knowledge base by making sure it looks and reads great for your customers, you'll save thousands down the line and reduce your customer support bill by an order of magnitude.