How to Write an Effective Knowledge Base Article

According to Statista, 88% of customers expect companies to offer an online self-service portal. Creating a great knowledge base article is the first step to promoting self-service. But how do you create a great knowledge base article? How do you choose which questions need to be answered in your knowledge base? And how do you measure if your knowledge base is successfully helping customers get quick answers, while unburdening your support team? Here’s a quick guide for you to write different types of knowledge base articles and help your customers find answers without any agent assistance.

What is a knowledge base?

A help desk knowledge base is a repository of information about your product or service. This curated resource portal can be leveraged to find answers to product-related issues or may contain a step-by-step guide to learn how to use the product or service. A modern knowledge base will support multiple formats of learning, including solution articles or FAQs, product manuals, tutorials, videos, and troubleshooting guides, all categorized into distinct themes or folders. It acts as the source of truth for the product or service to its stakeholders i.e. customers, employees, and partners. 

A knowledge base may be a part of a company’s self-service portal or may be a section on its homepage. For easy navigation, it’s advisable to add a search functionality that helps customers type in their queries to get directed to relevant resources right away.

Advantages of creating an effective knowledge base article

According to Forrester, self-service yields a better CSAT rating as compared to a virtual agent interaction. That’s not all. A knowledge base is equally useful for your customer support agents as much as it is for your customers. Your support agents can refer to the internal knowledge base articles to answer any customer queries quickly instead of reaching out to someone for guidance or trying multiple solutions. On the other hand, your customers can search for answers to common questions in the knowledge base instead of contacting your support team and waiting for a reply.

The end-to-end guide to an effective knowledge base article

It doesn’t matter what the size of your company is or the kind of industry you work for, getting started with the creation of a knowledge base is easy. You can even make use of a knowledge base software to choose a template of your choice, create the table of contents using search optimized article titles, and provide structured solutions to commonly raised concerns.

Remember: Your customers should just a web search away to your knowledge base articles.

There are no predefined rules to creating the best knowledge base article. You fail, learn and repeat. We have written hundreds of articles for our knowledge base, and it is used by over 150,000 customers. Having leveraged SEO to our advantage, we are still experimenting with the way we optimize our articles so they are easily searchable.

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

Getting started with a knowledge base article:

  • Answer FAQs
  • Onboard users

Before writing the knowledge base article:

  • Understand user pain-points
  • Write for the average user
  • Cater to different kinds of learners
  • Eliminate the writer bias

While writing the knowledge base article:

  • Tips to follow while writing the article

After writing the knowledge base article:

  • Interlink articles
  • Gather feedback

Getting started with a knowledge base article:

When you are creating your knowledge base for the first time, you will have a lot of topics to choose from. Start by collaborating with your customer support team to collect and analyze customer feedback. Enable your team to leverage these insights to deliver an exceptional customer experience by creating help articles that encompass step-by-step instructions to perform tasks in no time. You can even save time on creating your articles by creating knowledge base article templates for How to, User guide, FAQs, and more. 

One of the following techniques (or maybe both) should help you identify and prioritise which KBase articles to create first knowledge base:

  • Answer FAQs

What are the questions that have been frequently asked by your customers to your customer support team?

If you are not sure, browse through your support tickets from the past month (or week, if the ticket 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

Enlist these identified keywords and search terms. The next step is to start creating and adding these articles to your knowledge base.

  • Onboard users

Here’s a way to approach the creation of help articles. 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?

Collaborate with subject matter experts to write support articles that can assist your users in using the product/service to their advantage. Organize them based on the key features so that customers who visit your support portal can find them easily. You can also create a seamless customer experience for users visiting your support portal by creating playlists. This gives you an opportunity to categorize articles and let your customers transition to the next relevant article without the need to exit the portal.

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 gets launched.


Before writing the knowledge base article:

You have to make sure you have researched what you need to achieve before even getting started with a knowledge base article. Take time to understand and confirm the topics you should write about, identify customer pain points and determine the structure of your article.

  • Understand user pain points.

Before writing a tutorial, follow the step-by-step instructions yourself. You may even ask a couple more people to try the same. Take notes as and when you get stuck or about the steps that got others confused. Did something result in a delayed response? Do you need to rectify any of these aforementioned steps?

You might have a lot of tickets recorded on your helpdesk. Go through related tickets and find out where your users face issues. This approach will help you anticipate user pain points and questions, and present a way to eliminate or avoid these using troubleshooting guides. With the right software, your help desk can categorize tickets based on the queries raised, further reducing human effort.

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 comes easy for a power user may be too complex for an average user. If you feel like you need to explain more to a newly onboarded customer (wrt the information that a power user would like), split the use-case into multiple articles and link them to the original longer article. This way, the article written for the average user doesn’t need to have too much information.

For example, while explaining about 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 prefer a step-by-step manual to get started. You need to put yourself in the shoes of the customer to determine the format and the kind of resources that need to be shared using the article. Figure out the sufficient number of screenshots that make the process self-explanatory. Based on the customer behavior, you may also determine if it’s a better idea to incorporate a video instead. You may even 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 don’t fill the entire page with videos without text.

Note: We experimented with presentations and GIFs as a medium, but found that people need a quick solution and don’t wait to watch the different steps in the animation.

  • Eliminate the writer bias

You should not let your exposure to customer problems affect the article in a negative way. If you actively support your customers, you are likely to remember all the problems customers face as far as the features are concerned. If you are a tech writer, you are also likely to remember the step-by-step demo you received from the product manager.

Your article about a product feature should neither be a detailed explanation of the UI nor a mini-FAQ. It should be a mix of both. This allows users to understand and learn about the feature and find an effective solution to specific problems.

Here’s an article on SSO on our support portal to help our users understand remote authentication and address common user problems that may involve them getting locked out of their account.


While writing the knowledge base 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. Make sure you stick to the basics and 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 (use search terms in GA or by reading tickets). Use those words in the article, headings, and subheadings to help them understand your article easily.

2) Be straightforward.

Your articles need to be easy to scan through and understandable in just one read. You can create tutorials in a way that makes them easy to consume. If you want to improve customer experience, personalize the template, not the content (take a cue from Amazon).

Amazon knowledge base

3) Feature trumps benefits

When you write on a 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 more about the nuances of the features and not cover the benefits of using your product.

4) Treat every article as a mini-onboarding process

Start by explaining the feature in simple words. Then, use an example to walk the customer through the product interface and let them know what happens once they follow these instructions. This way, even if the setup process is elaborate, users will follow it through till the end.

5) Bullets and tables are your best friends

Needless to say, formatting solution articles is extremely important. Carefully choose your headers and subtitles. Structure your articles using bullet points and arrange your content using different sections. You may even make the action items bold in each step so it’s easy for readers to skim through your content.

6) Always state the prerequisites

Don’t make it hard for users to find out the limitations of a product. If your app doesn’t run on IE, say it. If this feature is available in the highest plan only, say it. You will save yourself from unnecessary grievances or concerns by being upfront about your services.

7) Nothing is too obvious

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

8) Do not sell.

Selling or upselling in support articles is like selling a support ticket (not recommended).


After writing the knowledge base article:

You’ve finally finished writing your article. You can now 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 updated from time to time and it serves the purpose of helping your customers resolve their issues by themselves.

  • Interlink articles

Go through the article you had just written one more time and find out if you can embed any other solution articles. Repeat the same exercise for the other related articles and provide links to the new article.

For example, if your new article talks 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 check if your article is actually helping your agents and customers. Has it reduced the number of tickets for this feature? Are other agents using this article to support their answers? If not, why?

Here’s a way we made life simple for our support team. Freshdesk’s knowledge base has a small survey at the end of every article. Every negative feedback gets converted into a ticket in the helpdesk in which the author is added as a viewer. This way, the author can quickly update the article based on the feedback received.

How to write an effective knowledge base article


  • Extend KBase to AI Chatbots

Integrate your knowledge base with your AI chatbot to automate FAQs for your customers. Chatbots offer self-service through conversation, reducing the effort of searching for answers in your knowledge base.

Smart chatbots learn from every customer interaction and offer intent-specific answers by pulling information from your knowledge base directly. Not just that, chatbots even go above and beyond to inform you of the gaps in your information and signal the scope for improvement of your answers.


Your checklist for writing a knowledge base article

Here are the steps you need to follow to write a knowledge base article:

  • Determine the topics that you need to cover
  • Structure the articles in an easily consumable format
  • Write the articles with the average user in mind
  • Add screenshots and videos especially when you explain something complex
  • Be detailed as well as specific to help all kinds of users
  • Format your articles
  • Interlink them
  • Get feedback from readers and improve them

A knowledge base article is perfected over time as you update it based on the feedback you receive from readers and support agents.

The perfect article also differs from business to business. You can follow this article to get started with the first few knowledge base articles, but once you get accustomed to the workflow, you can experiment and figure out what suits your customers’ needs. 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.

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

Your turn now.

What are some of the things that worked with your knowledge base articles? What are some articles that helped you out as a user? What are some best practices for writing a knowledge base article that you’ve learned from your experience?

Share with us in the comments below.


Originally published on Jun 1, 2018. Updated on February 16, 2022.

Leave a Reply

Your email address will not be published. Required fields are marked *

2 thoughts on “How to Write an Effective Knowledge Base Article

  1. Without having the significance, no article will be adored.People are only seeking for informative content from which they can learn.But nowadays quality and knowledge base article are hardly found. Most of the content or easy writer write for business branding and advertisement. It is not the ideology of blogging.For better writing, first of all, we have to change our mentally and we should set up our mentality to give something towards our readers. Your advice is also so authentic as well as fruitful to write a better blog post.Thank you for sharing.