perfectGuide to writing a knowledge base article

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.

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

At Freshdesk:

> 200 articles in the KB

> 40,000 people read them

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

Where do you start?

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

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

Before writing the article..

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?

UNDERSTAND USER PAIN-POINTS

Before writing the article,

A great example of anticipating questions, on the Udemy blog

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.

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.

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.

While writing the article..

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.

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.

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.

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.

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.

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.

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.

8. DO NOT SELL

While writing the article,

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

After writing the article..

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.

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.

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.

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.

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/