How to write a kbase article - while

How to Write a Perfect Knowledge Base Article

Written by on April 28, 2015

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.

A knowledge base is the one thing that can be instantly useful for both your support agents and customers equally.

No matter how big or small your company is, no matter what industry you are in, you cannot go wrong with a knowledge base (look at Google’s or Quizup’s). 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 kbase article. You fail, you learn and then you repeat. Here at Freshdesk, we have written hundreds of articles for our kbase, and it is used by over 40,000 customers. We have experimented quite a bit with our articles, and we constantly try to improve them everyday.

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

  1. Answering FAQs
  2. Onboarding users
  3. Understanding user pain-points
  4. Writing for the average user
  5. Catering to different kinds of learners
  6. Eliminating the writer bias
  7. Tips to follow while writing the article
  8. Interlinking articles
  9. Gathering feedback

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 too much 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 to your kbase by answering these questions.

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.

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 kbase article - before

Understanding 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 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 screenshots 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 amount of screenshots that will explain the process and whether that particular article deserves a video.

Of course, if you have the resources, it makes sense 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. They found that people have a hard time understanding the idea of bandwidth and created an explanation video for just that.

(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 so users can understand the whole feature by reading it and find solution for 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 your plans.

How to write a kbase article - while

 

1) Talk like the 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, personalize the design, not the content (take a cue from Amazon).

Amazon's kbase has personality
3) Feature trumps benefits. When you write for your support portal, make sure you’re not using marketing language. A solution article is written to help, not to convince. So unlike marketing content, emphasize 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 action items in each step.

6) Always state the pre-requisites. Again, this is not a marketing document. 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.

7) Nothing is “too obvious”. Do not 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 work is done and you can move on to the next one 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 kbase article - after

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 getting 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 tickets 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.

Freshdesk's kbase feedback

A knowledge base article cannot be perfected 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 kbase 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 article 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 “no-no”s  in a kbase article you have learnt from your experience? Share with us in the comments below.

Subscribe for blog updates