How to Write a Perfect Knowledge Base Article

Does your business need a knowledge base? Yes.

Is this the right time for you to set up a knowledge base? Yes, it always is.

Does your knowledge base give your customers everything they need? Maybe not.

Can you do something about it? Absolutely.

Let’s start from the beginning.

What is a knowledge base?

A help desk knowledge base is a set of information about your product or service that one can go through to solve related problems or to learn how to use the product or service. A modern knowledge base is usually a collection of articles that contain text, video, images, etc and is available on the internet. It acts as the source of truth for the product or service to its stakeholders like customers, employees, and partners.

Sometimes, it is a part of a company’s self-service portal. Sometimes, it is a part of their website.

Advantages of creating a solid knowledge base

A knowledge base is the one thing that can be instantly useful for both your support agents and customers. Support agents can refer to the knowledge base and answer the customer queries quickly instead of spending time asking someone for guidance or trying multiple solutions. Customers can search for answers to their questions in the knowledge base instead of contacting support and waiting for a reply.

No matter how big or small your company is, no matter what industry you are in, you cannot go wrong with a knowledge base. After all, searching for answers online is second nature for most of your customers.

But what can go wrong is your content. According to a Forrester report, self-service has a better satisfaction rating than virtual agent interaction, but customers often feel that the ‘content does not match customer expectations’.

There are no predefined rules to writing a perfect knowledge base article. You fail, you learn and then you repeat. Here at Freshdesk (and Freshworks), we have written hundreds of articles for our knowledge base, and it is used by over 150,000 customers. We have experimented quite a bit with our articles, and we constantly try to improve them every day.

Here’s a look at what has worked for us (and a little bit of what hasn’t):

Where do you start?

Before writing the article

While writing the article

After writing the article

Where do you start?

When you are creating your knowledge base for the first time, you will have a lot of topics to write about. One of the following techniques (or maybe both) should help you get up and running with your knowledge base:

Answer FAQs

Off the top of your head, what are the things most customers ask your support?

If you are not sure, go through your support tickets from the past month (or week, if your volume is huge). If that doesn’t give you enough information, find out what your customers are searching for by looking at your search terms in Google Analytics.

Tip: Connect your support portal to Google Analytics and get insights

Make a list and start adding articles that answer these questions to your knowledge base.

Onboard users

Write down the top 10 things your customers should be doing for them to see value in your product. Should they invite their team to use it? Should they import data from their previous system?

Write support articles for all these steps and organize them based on functionality so that customers who visit your support portal can find them easily. And go through them one after the other (kind of like a playlist).

While answering FAQs will help your agents immediately, writing articles that help onboard new users will help you in the long term. We started out by writing basic FAQs and now, we write articles for every new feature that goes out and link it inside the product.

Before writing an article:

Most of the work in coming up with a knowledge base article is done before you actually write it. You have to make sure you understand what you are writing about, find pain points and put a structure around your whole article.

How to write a perfect knowledge base article

Understand user pain points.

Before writing a tutorial, try the entire step-by-step procedure yourself (and with a couple more people if you can). Note down where you got stuck, which step was confusing, what made you wait and any other mistakes you did along the way.

If you have a lot of tickets in your helpdesk, you can also go through related ones and find out where users have a problem. This way, you can anticipate user pain points and questions, and eliminate them in the article.

Example of understanding user pain-points

A great example of anticipating questions, on the Udemy blog.

Write for the average user

You are not writing your knowledge base articles for just one kind of customer. What is easy for a power user may be too complicated for an average user. If you feel like you need to give more explanation for a newbie (or more information that a power user would like), split them into multiple articles and link them to the original one. This way, the article written for the average user doesn’t have too much information.

For example, while explaining the social tab in Freshdesk, instead of just telling users ‘You can search Twitter using the social tab’, we wrote a separate article on how to search on Twitter (that a power user wouldn’t need) and linked it to the original one.

Cater to different kinds of learners

Different people learn differently. Some like to learn using images and videos while some like to try out things step by step. That doesn’t mean you can bog down the article with screenshots. Figure out the minimum number of screenshots that will explain the process, and whether that particular article deserves a video.

If you have the resources, it makes sense to add a video at the end of every article.

Take Wistia’s FAQ section for example. Even though they’re a video-hosting company, they didn’t fill the whole page with videos without text.

(Note: We experimented with presentations and GIFs as a medium, but we found that people don’t wait to see the different steps in the animation)

Eliminate the writer bias

You should not let the exposure you have to customer problems affect the article in a negative way. If you actively support customers, you are likely to remember all the problems customers have with the feature you are writing about. And if you are a tech writer, you are likely to remember the step-by-step demo you received from the product manager.

Your article about a feature should neither be a detailed explanation of the UI nor a mini FAQ. It should be a mix of both.

This way, users can understand the whole feature by reading it and find the solution to specific problems.

Here’s an article on SSO in our support portal that helps users understand remote authentication and, at the same time, addresses common user problems like getting locked out of their account.

While writing the article:

Now that you’ve figured out what you should be writing about and what points you should get across, it’s time to actually write the articles. Here, you should make sure you stick to some basics and you actually follow through on your plans.

1) Talk like your users talk.

Do not use over-the-top words or technical jargon in your articles. Find out what customers call the feature you are writing about (using search terms in GA or by reading tickets) and use those words in the article and its title.

2) Be straightforward.

Your articles need to be easy to scan through and understandable in just one read. The title and subtitles should cover what you are trying to say. If you are interested in making things look good, personalise the design, not the content (take a cue from Amazon).

Amazon Knowledge base

3) Feature trumps benefits.

When you write for your support portal, remember that you are not trying to sell. A solution article is written to help, not to convince. So your articles should talk about the nitty-gritty of the features more and benefits less.

4) Treat every article as a mini-onboarding process.

Start by explaining the feature in simple words. Then, use an example to show what the customer can do once she follows your instructions. This way, even if the setup process is elaborate, users will stick to it till the end.

5) Bullets and tables are your best friends.

Needless to say, formatting solution articles is extremely important. Clearly, differentiate your titles and subtitles. Split different sections using a horizontal line. Bold the action items in each step so it’s easy for readers to skim.

6) Always state the prerequisites.

Don’t make it hard for users to find out what a feature cannot do. If your app doesn’t run on IE, say it. If this feature is only in the highest plan, say it. You will save yourself from a getting a lot of grief by being upfront.

7) Nothing is too obvious.

Don’t leave out even the tiniest of details assuming that it’s obvious. Use a table or create annotated screenshots when you want to explain many little things without making the article too long.

8) Do not sell.

Selling or upselling in support article is like selling in a support ticket (also bad).

After writing the article:

You’ve finally finished writing your article. All your work is done, you can move on to the next task and forget about this one, right? Nope.

You are not done writing a support article once it’s published. You have to make sure that it is useful, that it’s up-to-date and that it is organized well.

How to write a perfect knowledge base article

Interlink articles

Go through the article you just wrote one more time and find out if you can link out to any other solution articles. Then, go through other related articles and provide links to the new article.

For example, if your new article is about plans and billing, you can link it to the one about payment options. This helps readers navigate easily (even if they land up there by mistake) and it increases the chances of the article being found on search engines.

Actively listen to feedback and improve

A few days after your article is published, you can figure out if your article is actually helping your agents and customers. Has it reduced the number of questions about this feature? Are other agents using this article to support their answers? If not, why?

Freshdesk’s knowledge base has a small survey at the end of every article. And every negative feedback gets converted into a ticket in the helpdesk in which the author is added as a watcher. This way, the author can quickly update the article based on the feedback.

How to write a perfect knowledge base article-How to improve an article



Bonus tips

Here are some of the tools we use to create our knowledge base content:

  • Google docs – to collaborate with multiple stakeholders
  • Freshdesk – as a knowledge base provider
  • Quicktime – to record screencasts
  • Sketch – to annotate screenshots and create graphics
  • Grammarly – to spell check the articles

Writing a knowledge base article – Checklist

To summarize, here are the steps you need to do to write a knowledge base article:

  1. Finalize the topics that you need to cover
  2. Structure the articles in an easily consumable format
  3. Write with the average user in mind
  4. Add screenshots and videos especially when you explain something complex
  5. Be broad as well as specific to help all kinds of users
  6. Format your articles
  7. Interlink them
  8. Get feedback from readers and improve them

A knowledge base article cannot be perfect right away. It is perfected over time as you update it based on the feedback you receive from readers and support agents.

A perfect article differs from business to business. You can follow this article to get the first few knowledge base articles off the ground, but once you get the hang of it, you can experiment and try to find out what suits your customer base. Even if you cannot see the effects of the articles on your users right away, it will be helpful to your agents from day 1. It is also a great way for new agents to get up to speed with your product/service.

Your turn now.

What are some of the things that worked with your knowledge base well? What are some articles that helped you out as a user? What are some definite don’ts to keep in mind while writing a knowledge base article that you’ve learned from your experience?

Share with us in the comments below.