Knowledge Base Article Health Check: What to Examine Before You Hit Publish

Each time I hit send on our monthly Bookmarked newsletter, I get a rush of nervousness. There might've been a typo. Or a missing link. Maybe it wasn't at all responsive, and it looks terrible on mobile. There are so many things to look out for that it's tough to spot the small stuff.

When a customer got in touch with us recently about wanting a health check before they published their Knowledge Base article, it got me thinking—what should you look out for before launching your self-serve help? Are there ways to speed up the process?

It's a gruelling job looking through hundreds of Knowledge Base articles and making sure they're all publishable. That's without thinking about the organization and structure.

This post contains a few things—what to look out for before launching your Knowledge Base article and how to fix them without working up a sweat.

What to Look Out for Inside Your Knowledge Base Articles

Giving your articles another look can be a tedious task, but it is an important one before launching. A typo can easily throw off a customer when they're trying to read through instructions, or worse still—they might get a worse impression of your brand afterwards.

There's your typical SPAG (spelling, punctuation, and grammar) you'll want to check over, but that's not all. You'll want to make sure it's digestible, flows nicely, and it's easy to navigate.

Check the Readability

Readability is as important as SPAG when it comes to Knowledge Base articles. An article full of jargon and complicated words can make your article far less accessible. Even if your audience is highly educated you’ll want to use low-level words where possible—you want to convey information in the most digestible way, not make them pull up a dictionary.

"Machines are great and all but common sense should still prevail."

There’s plenty of options when it comes to checking the readability of your Knowledge Base article. In HelpDocs there’s one built-in. It uses the Automated Readability Index which is a scale from 1 to 14—the lower the number the easier (and more accessible) the content inside is.

Red circle around the words '8 readability' indicating an average readability score for the knowledge base article.
Readability inside the HelpDocs text editor

🧠 The HelpDocs readability calculator can see past your formatting so you’ll get an accurate result every time.

There’s a bunch of other tools you can paste your content inside of to get an accurate picture of the readability. Grammarly is a popular one but there’s also free ones on the Internet. Just type “readability checker” into Google.

A Google results page for the term readability checker
Google results for "readability checker"

You'll want to make sure you take the advice of an automated readability checker with a pinch of salt, though. Machines are great and all but common sense should still prevail.

Invite and Ask Your Audience Privately

The best feedback you can get with readability is your audience. Does the Knowledge Base article make sense? Does it have a natural flow to it? You could think about sharing the private article or password protecting your entire Knowledge base to get feedback without making it public.

HelpDocs Shared Password page

To automate this process you can use one of our feedback integrations to gather insights. Our Doorbell integration lets visitors write written feedback when they press on the neutral or negative feedback icon. With Feedier you can run surveys based on the page URL.

"Keep the survey going to get deeper insights into how your audience resonates with your article."

Again, there’s a bunch of different tools you can use to collect feedback on the page. You can even automate this process using Hotjar or Fullstory so you don’t even need to gather 1-on-1 input from users.

And this doesn’t have to stop when you publish your Knowledge Base article. Keep the survey going to get deeper insights into how your audience resonates with your article.

Analyze Your Formatting

A critical part of writing an informative article is to format it correctly. It’s not just the words you use but how they look to the reader. In HelpDocs there are quite a few ways to format your articles with callouts, ordered lists, tables, and more.

Let's say you have three callouts in a row. Is that the best use of space? Putting more than two callouts together might distract from the message you're trying to convey. Using a table might be a better use of space 👇

Looking at the format of your articles is a manual process but one that should be relatively easy to spot. If something looks a little off then you're probably not the only one who thinks that.

It's a skill you'll have to develop over time but one that's useful. Try to put yourself in your user's shoes and see what might look wrong.

Add Your Meta Information

Meta descriptions are one of those things that people often miss. They matter because they help guide your users both on search engines and inside your Knowledge Base.

Customizing an Article Slug, Meta Description & Short Version
When you first get started writing your articles, you’ll notice a lot of the advanced stuff is automatically done for you. However, if you’re a whizz and want to customize the way things are displayed on your knowledge base, you can!

Meta descriptions often include the title, the URL, and the description of your article. All these things make it easier for search enginers to crawl your content and users to find what they're looking for.

Keep Accessibility Top of Mind

Accessibility is a big topic on the web at the moment—and rightfully so. Everyone has the right to access the web and so you should make it as easy as possible. With Google launching updates to make accessibility a priority when ranking results it should be something you're thinking about.

"You should make sure you're using inclusive language so everyone feels welcome."

Accessibility means everyone can access your content. And that doesn't just mean people with disabilities. You should make sure you're using inclusive language so everyone feels welcome.

There are a few ways you can check your accessibility. The first is to make sure you're writing alt text where it makes sense. The A11Y Project has a fantastic resource over here that explains it much better than I could.

Quick tip: Using alt text properly - The A11Y Project
A few tips on how and when to use the alt attribute. Make sure the text is helpful and most importantly meaningful.

In a Knowledge Base article the alt text would most likely explain what the image is showing. Rather than writing "Image of the HelpDocs dashboard", you'd want to write something like "Red circle around the words '8 readability' indicating an average readability score for the knowledge base article" so the user doesn't have to guess what the image includes if they're using a screen reader.

Iterate and Improve

Publishing your Knowledge Base article doesn't need to be such a big deal. Most of the time it's just a matter of checking off a list of things that need to be created and reviewed.

And never fear—if you don't get it quite right the first time you can always get feedback from users or look at your analytics and improve. Creating good Knowledge Base articles is a skill that takes time and practice.