ICMI is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.


Use Customers' Questions to Build Better Knowledge Base Articles

To write great knowledge base articles, you should think like a tailor. To make a bespoke suit jacket, a tailor takes many measurements, everything from the width of the shoulders to the circumference of the wrist. All those measurements enable the tailor to create a jacket that matches the unique dimensions of the wearer’s body.

Useful knowledge base articles must “fit” the user’s needs, whether the user is a tech support analyst, a business user, or a retail shopper. But too often, we rely on vague, one-size-fits all templates to create knowledge base articles. And these templates do very little to help us write good KB articles.

Two commonplace but not-very-useful templates for knowledge base articles in tech support

Chart of templates

Where’d you hide the instructions?

It’s easy to see the biggest problem with these templates. Most knowledge articles include a numbered set of steps the user should follow to complete a process or solve a problem. Most users are avidly searching for these numbered instructions, but Templates 1 and 2 use the words “Body” and “Details” to indicate the section of the article where the numbered steps will go. These KB article templates are like the pattern a lazy tailor would use: “If I make the sleeves 34 inches long, the jacket will perfectly fit men who are 5’ 10”. The rest of the men (and all women) can just roll up the sleeves or wear a long-sleeved dress shirt underneath to fill the gap.”

Why are your section headings so bland?

We know why organizations create KB templates that have generic section headings. They want to ensure KB article writers can use the templates whether they’re writing the “How to Change Your Password” article or the “How to Set Up the ABC Digital Workspace Solution on an iOS Device” article. But generic section headings don’t provide enough structure, so they aren’t very helpful for the KB article writer or the user. In fact, a heading like “Body” is really poor. “Body” communicates “Most of the stuff in this KB article is in this section, but you have to read the section to find out what it’s about.”

User questions make great section headings

Chart of template options

To create a better KB article template—one that’s easier for writers and users alike—you must create better section headings. Here’s a handy, reliable approach: use users’ own questions as the headings in the KB article template. Instead of putting the instructions in a section named “Body” or “Details,” I’ve used the questions users are likely to ask. Here’s how a “How to Change Your Password” article might look with user questions as headings.

How can you create a list of user questions that would work in any and every knowledge article?
To be blunt, you can’t. Your knowledge base is large, and it contains articles on myriad and varied topics. Your KB article users’ questions will vary by article topic, process, newness, and urgency. If you use generic user questions as template section headings (for example, “How do I do this?”), you’ll end up right back where you started with a generic KB article template and meaningless section headings like “Body” and “Details.”

You have a couple of great options. First, you could create a handful of KB article templates and populate them with likely questions users have on that topic. For example, here are two commonplace templates all technical support knowledge bases include: “Getting Started” and “Troubleshooting.” You could prepopulate these with user questions. The KB article writer would use, delete, or add user questions as the topic of the article dictates.

Third chart

User questions help KB article writers, too

If you have a dedicated team of word-loving professional technical writers creating your KB articles, you are fortunate indeed. It’s more likely that you’re requiring your technical support analysts to write and update these articles. Some of them are good writers, but some are…not. Show these well-informed support analysts (some of whom are reluctant or unskilled writers) how to use user questions as template headings.

This will make their writing process easier and the KB articles better. Why? Because using user questions as headings forces the writer to think of what the user will ask. These questions enable the writer to imagine the user, and thinking of your user as a real person with questions is the best way to write help content.