How to Write a Great Knowledge Base Article | USU Software

I’m not going to lie. Writing a great knowledge base article is a lot of work. Your writing must be precise, concise, and easy-to-read. You must know your topic really well, and then you must try to un-know it, so you can think like your reader—who wouldn’t be reading your KB article if they knew as much about the topic as you do. 

But take comfort in knowing that your substantial writing effort will pay off. Your readers will get the information they need, your high-quality knowledge content will build customers’ trust in your company, and you’ll sell more products and services.

Here are seven of my best tips on how to write a great knowledge base article. Like I said, I’m not going to lie. Some of these tips are easy to follow, and others will require you to invest the time in your word craft. If you need motivation, please remember that enabling self-service means avoiding hand-holding. Only high-quality content can enable self-service.

1. Include a verb in the article’s title

The title of your knowledge base article should help the search engine serve up the right content (keywords) and the human reader confirm, “Yep. This is the article I need.” The best KB article titles include verbs because a group of words with a verb in it is usually a clause, which makes the title a complete, concrete thought.

Here are three ways to write article titles that include verbs.

• Use the reader’s question for the article title: “How Do I Find Funding For My Community Nonprofit Organization?” The benefit to this FAQ-style naming approach is that readers see their own questions and feel confident in the KB information provided.
• Use the problem for the article title: “I Can’t Find Funding For My Community Nonprofit Organization.” If you know that your KB readers begin their knowledge search when they’ve experienced a problem, this title approach may be best.
• Use the solution for the article title: “Find Federal Programs That Fund Community Nonprofit Organizations.”

Avoid a topic title. Topic titles lack verbs, so they’re less specific and less helpful than other types of titles. The topic title “Funding for Community Nonprofit Organizations” is OK, but it doesn’t imply that the article will help the reader find funding, which is probably the kind of help they want. Few readers if any are just curious about funding.

2. Address your reader directly: use the pronoun “you”

When people are reading KB content, they have one big, overarching question: “Is this the information I need or want?” To reassure them that they’ve found the right article, write directly to them, using the second person pronoun “you.” Write “You can update your account information…” instead of “Users can update account information…” (Remember, users don’t refer to themselves as “users,” so you shouldn’t refer to them that way either.)

What should you do if there’s more than one “you”? Let’s say you’re writing an article for a financial institution’s knowledge base and your readers will be both account managers and account holders. You’ll confuse people if you use the same “you” to refer to two different groups of users who may have different permissions or be following different steps, etc. Here are a couple of work-arounds:

• Use headings that call out the content for each type of user. In this example, you’d write these headings: “For Account Managers” and “For Account Holders.”
• Use “if you are…” statements. Write, “If you are an account manager, you will…” and “If you are an account holder, you should…,” etc.

3. If your KB article focuses on the solution, identify the problem, too (and vice versa)

Let’s imagine you’re writing an article for a city government’s knowledge base, which is used by city residents. The title of your article is “Dispute an Incorrect Trash Service Charge,” and the article explains the steps a resident should take when they’ve been charged incorrectly for trash service.

Your article is about the solution, but you should also briefly mention the problem. So, you could begin the article by writing, “If you’ve received a duplicate trash service charge or if you’ve been charged for a recycling bin you do not have, follow these steps to dispute the incorrect charge.”

Or, you could be writing the same article with a focus on the problem. In that case, you might title the article “I’ve Been Charged Incorrectly for Trash Service.” Begin this article by explaining the solution. You could write, “You can formally dispute an incorrect trash service charge, and the city’s Solid Waste Department staff will review your account and issue you a credit, if necessary.”

Solution or problem? Should most of your knowledge base include articles that focus on the solution or the problem? That depends on how your readers think and what they ask. If few city residents are aware that they can dispute incorrect trash service charges, but many do complain about those charges, it’s better to focus on the problem: “I’ve Been Charged Incorrectly for Trash Service.” Each article should mention both the problem and its solution, so each article has the best chance possible to meet the reader’s needs.

4. Use headings and lists to make the article easy to scan

We know readers aren’t going to read the KB article thoroughly from top to bottom, so it’s our job as writers to make the article easy to scan. To make our writing scannable, we must include scannable features such as headings and lists. (If we omit scannable features, people will still try to scan our content, but they won’t do it successfully.)

Here’s a KB article from a local government knowledge base with the somewhat inauthentic title, “Do I need to consider zoning before I apply for a building permit?” (Side note: Don’t write “fake question” KB titles. Of course a prospective builder needs to consider zoning! A better title would be something like “How do I review zoning requirements before I apply for a building permit?”)

The original version of this article lacks the headings and lists that will help readers scan to the section they need. I’ve provided a revised, scannable version.

Just by looking easier to read, a KB article with headings and lists motivates the reader. If we want people to use our self-service options, we must make them look like they won’t be a ton of work.

5. Use relevant visuals, but add commentary

Many knowledge base articles have more visual content, especially screenshots, than they do written content. That’s OK. If showing your reader what the screen will look like is the best way to help them complete a task or understand a process, then provide screenshots galore, by all means.

However, expert KB article writers never provide screenshots without commentary. Here are examples of screenshot commentary in knowledge base articles provided by Digital Services Georgia (a state agency):

• Write a title for the screenshot. In the article “How do I get rid of the extra space on my homepage/Landing Page?,” the first screenshot is titled “There’s extra empty space on my Landing Page,” which helps readers immediately understand what they are seeing.
• Write a caption for the screenshot. The “Why is my image cropping? ” article uses captions above each image.
• Associate instructions or components with the screenshot. The “Call to Action” KB article uses numbers to indicate the five components of a call to action.
• Use arrows, highlighting, or callouts to direct the reader’s attention in the screenshot. For example, the article “Why won't my link URL update?” includes a red call-out box in the Solutions screenshot.

6. Use internal hyperlinks for long articles

Internal hyperlinks help KB article writers cope with the “Goldilocks” problem. We don’t want to drown readers with articles that are too long, but we don’t want to leave readers thirsty for information with articles that are too short. Internal hyperlinks allow us to write articles that—with the click of a link—will be just the right length for individual readers.

Internal links also help readers move easily through or to the sections of a KB article, which is important. We know readers may return to a KB article several times as their need for and understanding of its content changes. Internal links will help them find the info they need, and skip the info they’ve already acquired.

7. Offer access to more — and deeper — information (but segregate it)

It’s a good idea to offer a Read More, Learn More, or Related Articles section in your KB article, but place the “More” list at the end instead of linking to the related information within the article body.

Final Thoughts

It’s not about the font. It’s not about the word count. And it’s certainly not about the fancy technical terms. Writing a great knowledgebase article is all about the reader. If you can anticipate and answer your readers’ questions on a topic or process, you can write a great knowledge base article.