1) A knowledge base article is perfected over time through updates based on feedback from readers and support agents. 2) Customers often feel that content in knowledge bases does not match their expectations. 3) There are no set rules for a perfect knowledge base article, but some tips that worked well include answering FAQs, onboarding users, understanding pain points, and gathering feedback.

1. perfectGuide to writing a
knowledge base article

2. 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.

3. 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”.

4. At Freshdesk:
> 200 articles in the KB
> 40,000 people read them

5. There are no predefined rules to writing a perfect KB article.
Here are some pointers about what worked for us:
• Answering FAQs
• Onboarding users
• Understanding user pain-points
• Writing for the average user
• Catering to different kinds of learners
• Eliminating the writer bias
• Tips to follow while writing the article
• Interlinking articles
• Gathering feedback

6. Where do you start?

7. 1. By going through old tickets for a week or a month,
2. By connecting your support portal to Google Analytics
and looking at the search terms,
3. Or just based on your experience and intuition.
Make a list of the most common support questions,
Start your KB by answering these questions.
ANSWER FAQs
Starting a knowledge base

8. 1. Make a list of the 10 things a new customer should
do to start seeing value in your product.
2. Start your KB by writing articles for these steps.
3. Organize them based on functionality so that
customers who visit your support portal can find
them easily.
ONBOARD USERS
Starting a knowledge base

9. Before writing the article..

10. UNDERSTAND USER PAIN-POINTS
• Try the entire step-by-step procedure yourself
and note down:
• Anticipate these user pain points and questions,
and eliminate them in the article.
Before writing the article,
1. Where you got stuck?
2. Which step was confusing?
3. Which step made you wait?
4. What mistakes did you do along the way?

11. UNDERSTAND USER PAIN-POINTS
Before writing the article,
A great example of anticipating questions, on the Udemy blog

12. WRITE FOR THE AVERAGE USER
Write them as separate articles and link it to the
original one written for the average user.
Before writing the article,
1. Do you need to give more explanation for a newbie?
2. Do you need to give more information for a power user?
What is easy for a power user may be too complicated for an average user.

13. CATER TO DIFFERENT KINDS OF LEARNERS
Some like to learn using screenshots and videos while
some like to try out things step-by-step.
Before writing the article,
1. Use the minimum amount of screenshots that will
explain the process.
2. If the process is complicated, explain using a video.

14. ELIMINATE THE WRITER BIAS
Do not let the exposure you have to customer problems
affect the article in a negative way.
Before writing the article,
1. If you actively support customers, make sure your article
about a feature isn’t just about common customer
problem and its solutions.
2. If you are a tech-writer, make sure your article is not just
a detailed explanation of the UI.

15. While writing the article..

16. 1. TALK LIKE THE USERS TALK
Do not use over-the-top words or technical jargon.
While writing the article,
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.

17. 2. BE STRAIGHTFORWARD
While writing the article,
1. Make the article easy to scan through and
understandable in one read.
2. The title and subtitles should cover what you
are trying to say.
3. Personalize the design, not the content.

18. 3. FEATURE TRUMPS BENEFITS
A solution article is written to help, not to convince
While writing the article,
So unlike marketing content, emphasize the
features more and benefits less.

19. 4. TREAT EVERY ARTICLE LIKE A MINI-ONBOARDING PROCESS
While writing the article,
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.

20. 5. BULLETS AND TABLES ARE YOUR BEST FRIENDS
While writing the article,
Needless to say, formatting solution articles is extremely important.
1. Clearly differentiate your titles and subtitles.
2. Split different sections using a horizontal line.
3. Bold action items in each step.

21. 6. ALWAYS STATE THE PREREQUISITES
While writing the article,
Don’t make it hard for users to find out
what a feature cannot do.
1. If your app doesn’t run on IE, say it.
2. If this feature is only in the highest plan, say it.

22. 7. NOTHING IS “TOO OBVIOUS”
While writing the article,
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.

23. 8. DO NOT SELL
While writing the article,
Selling or up-selling in support article is like
selling in a support ticket (also bad).

24. After writing the article..

25. INTERLINK ARTICLES
After writing the article,
1. Go through the article you wrote one more time
and find out if you can link out to any other
solution articles.
2. Go through other related articles and provide
links to the new article.

26. ACTIVELY LISTEN TO FEEDBACK AND IMPROVE
After writing the article,
1. Has reduced the number of questions about this feature.
2. Is used by other agents to support their answers.
A few days after your article is published, find out if the article:
Have a feedback system in place to make sure that
it’s useful, up-to-date and organized well.

27. FRESHDESK’S KNOWLEDGE BASE SURVEY
Every negative feedback gets converted
into tickets in the helpdesk.
The author of the article is added as a
watcher to the ticket.
A small survey at the end of every article.

28. A perfect article differs from
business to business.
You can follow this article to get the first few KB 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.

29. Read more about writing a perfect knowledge base
article over at the Freshdesk blog:
“Behind every slideshare is a great blogpost”
http://blog.freshdesk.com/writing-a-knowledge-base-article/