Tips & Templates for Writing Great Knowledge Base Articles

When a customer hits a snag while using your product, the first thing they interact with won’t likely be a helpful member of your team — it’s more often a knowledge base article.

Much like your front door, you want to make your knowledge base articles as welcoming and friendly as possible. By defining and following knowledge base best practices, your team can ensure that this integral part of the customer experience is as helpful and impactful as possible.

We’ve collected a whole list of knowledge base best practices to make this process easy for you. Beyond that, you’ll find several knowledge base article examples and learn how to go about creating templates for them so it’s even easier to build effective documentation.

What is a knowledge base article?

A knowledge base article is a piece of online documentation that answers a frequently asked question or provides instructions for solving a problem that customers commonly run into. Common knowledge base article types include informational articles, how-tos, troubleshooting guides, and FAQs.

Knowledge base articles are helpful for customers in all stages of their lifecycle, but they are incredibly impactful during the “help me help myself” phase of exploring your product.

But as Kathy Sierra shares in her book Making Users Awesome, companies often drop the ball with post-purchase publishing. Help content is usually one of the first things to feel the sting of mediocrity.

And while a knowledge base tool like Help Scout Docs makes it easy to create visually compelling knowledge base articles, clean, organized writing doesn’t come in the same turnkey fashion. It takes a sincere effort.

Discover the power of self‑service

Create and publish answers for customers and reduce your customer support volume by at least 20% with Help Scout Docs.

Try for free

8 best practices for writing effective knowledge base articles

The best help content is informative, engaging, unquestionably straightforward, and mindful of how and why a customer searched for help in the first place. To build knowledge base articles that meet all of those criteria, follow these eight best practices.

1. Don’t make assumptions

Customers turn to your self-service documentation to solve problems, so your most important goal is to be incredibly clear. Customize the tone that you use in your documentation for the audience reading it.

For instance, write your basic help desk articles imagining that the people reading them are complete beginners. Save the advanced terminology and jargon for advanced documentation, and be wary of mentioning to-dos in passing. It’s safer to assume that customers will need guidance for each step.

For example, if a customer is looking up how to migrate their website to a new host, which one of the following leaves the least room for error?

• Before you continue, make sure to change your IP address.

• Before continuing, change your IP address by going to Settings > Manage Domain > IP Address.

Option one assumes that the reader knows how to change their IP address, while option two meets the needs of both customers who know how to change their IP addresses and those who don’t.

Don’t self-sabotage by making assumptions about “simple” instructions. It’s better to over-communicate. More experienced users can simply skim past instructions they don’t need, but beginners will hit hurdles when you leave critical details out of your documentation.

Similarly, use pictures and videos where you can to ensure that nothing gets lost in translation. You may know what a specific term means, but it will be easier for your customers to understand if you show them what you are talking about.

2. Use anchor links in lengthy articles

Avoiding assumptions means that you may sometimes have to write lengthier knowledge base articles to ensure you’re explaining every step of the process.

When writing a longer article, include a table of contents with anchor links to make it easy for more advanced users to skip past the information they don’t need and navigate directly to the details they’re looking for.

Even for average-length articles, users will appreciate being able to jump to the section they want. Links are also handy for list-type knowledge base articles like FAQs or best practices.

As an added bonus, well-structured documents also help search engines index specific sections of your content, making it even easier for your users to find them in a search.

3. Make the content easy to skim

Especially if you are writing significantly longer knowledge base articles, it’s essential to ensure that you don’t intimidate readers with a wall of text. When solutions aren’t easy to find, contacting support will be the customer’s next step, and no one wants to have to wait to resolve an issue.

Designer Rafal Tomal shows how proper use of subheadings and line breaks are a shortcut to an easily scannable document:

Use headers, callouts, bullet points, spacing, and visuals to highlight important information and keep the complete set of instructions visible at a glance.

Here’s an example from our Docs knowledge base article about getting started with Workflows:

It uses various types of formatting — bolding for navigational elements, an ordered list for steps in the process, and a different background color for a note — that attract attention to the critical pieces of information on the page. A reader scanning to find pertinent details will quickly find what they need.

4. Make things easy to read

A few key points to consider when you’re writing for a knowledge base are:

• Write as you would speak to a friend, but edit to clarify your thoughts. Your knowledge base articles shouldn’t read like a stream of consciousness.

• Consider your readers’ goals: Is the knowledge base article about learning the ins and outs of your product (curious) or fixing a bug or problem (frustration)? Adjust your tone and your content accordingly.

• For articles on non-troubleshooting issues, a bit of humor is fine, but the line of annoyance is quickly crossed. Consider what frame of mind your customer will be in when they get to your knowledge base article, and write to that point.

• Avoid slang and anything that may have an alternate meaning.

• Get to the point quickly and simply. Some knowledge base editors offer AI features that can help cut out any extraneous content.

Stick to your brand’s tone guidelines while also writing the most practical knowledge base articles for your reader base. One of the best resources on the web for honing your voice in writing is Mailchimp’s Voice and Tone guide, which is a great resource for developing your own style guide.

5. Organize your knowledge base article logically

Good knowledge base articles become great when they’re designed around the reader’s workflow. As you create your knowledge base article process, add a step to consider where your customers will be when they read your articles.

Unless you want your customers to feel confused and disoriented and become even more frustrated, getting the flow right is vital. Here are three principles to live by:

1. Chronological order: It’s a must to organize a piece of help content in the chronological order of steps. The first thing your customers should see is the first step in the process they need to take to succeed.

2. Order by difficulty: If multiple tasks can be performed “first” (i.e., the order doesn’t matter), have customers do what’s easiest first. Early friction decreases the likelihood that they’ll finish or even follow your advice, so begin with a quick win.

3. Be mindful of workflow: Structure responses in a way that sustains activity and momentum. Avoid interrupting a problem-solving workflow until near the end.

Ensure you’re addressing related questions and issues by closing the article with a quick list of common follow-up questions, like in this example:

Put yourself in the customers’ shoes and consider what follow-up questions or needs they might have, and then answer them proactively.

6. Use links strategically

Including links in your knowledge base articles is a great way to direct customers to other details and instructions they may need. It also helps you stay focused on the topic at hand without covering every possible issue or piece of help a customer might need.

While linking to other helpful articles is a best practice, it’s important to use links strategically. If you link to the wrong things at the wrong time, you increase the chance of readers getting distracted or more deeply confused. You want to nudge customers to click links only when following a link is the natural next step.

Besides embedding links directly into your content, you can also include related articles at the end. As mentioned above, including related knowledge base articles on topics that your reader might be curious about next is a great way to proactively help them move forward in their journey.

7. Stick with simple article titles

Restrain your creativity in favor of clarity, and keep titles as straightforward as possible. When stuck, ask yourself: What might a customer search for?

Better yet, if your knowledge base article tool offers insights like this, you can even look at what searches your customers have made and whether the search results returned anything. If you are a Help Scout user, our Docs report is excellent for this:

Optimize your knowledge base article titles based on what people are searching for.

This list is also a great resource when trying to determine what to write. If you see that people are regularly searching for a document or category that you don’t yet have, you can use this search functionality to guide your documentation strategy moving forward.

Remember that people search with basic phrases. For instance, instead of “how to migrate your WordPress website,” they’d likely use “migrate WordPress site.” Create titles that include the operative phrases.

If you’re a Help Scout user searching for information on “forwarding emails,” our knowledge base returns the following:

None of the titles are exciting. Instead, they’re straightforward — just as they should be.

Additionally, rely on action words in the active voice for a majority of your titles:

• “How to (Blank)”

• “Using (Blank)”

• “Setting Up (Blank)”

Or use exact phrases of the actions they’ll take, such as “uploading your first video,” “installing your plugin,” and so on.

8. Use images to save time and create clarity

“Show, don’t tell” is important to remember when creating knowledge base articles. When you’re walking customers through how to do something in your system, you can write fewer words and make your instructions clearer by including screenshots or GIFs showing each step in your interface.

For instance, if a Help Scout customer wants to learn more about assigning conversations, this is what they would see in our documentation:

Each explanatory paragraph of text is followed by a screenshot showing customers exactly what they should see when performing that step.

4 knowledge base article templates and examples

Now that you know how to write excellent knowledge base content, let’s break down the different types of knowledge base articles and look at how you can create templates for them. Templates help keep the knowledge base article process clean and easy for your team whenever they need to make new content.

1. Informational articles

Informational articles help to review a specific system, function, or feature within your product.

They are not designed to describe problem-solving steps or get into the technical nitty-gritty of a particular feature. Instead, they educate the user on something they aren’t familiar with and provide an overview of any features or options available within it.

Here’s an example of an informational article from our support knowledge base:

This article, Understanding reports in Help Scout, is an overview of the reports functionality in Help Scout. Right at the top, we explain what this informational knowledge base article is about and provide quick links to jump to whatever topics are relevant to the reader.

Informational article template

2. How-to articles

How-to articles are similar to informational articles in that they describe how to use a specific feature without additional troubleshooting steps. They are typically structured as a list and should be limited to a single feature or task, like changing a password or adding a new user.

Here’s an example of a how-to article from our support knowledge base:

This article, called Forward Conversations Outside of Help Scout, is a how-to that includes a list of steps to take to share a Help Scout message with someone who doesn't have an account.

The article also includes information on how to keep to keep track of conversations that have been forwarded.

How-to article template

3. Troubleshooting articles

Troubleshooting articles address a specific problem that a customer is having and offer steps to resolve it. Just like how-to articles, troubleshooting articles need to focus on one particular issue. While you can have multiple different options for troubleshooting, they should all be focused on a single problem.

For instance, you may have four different processes by which someone could resolve an issue with their browser. All four processes have a place in the troubleshooting article, but they all need to fix the same problem.

Here’s an example of a troubleshooting article from our documentation:

This article, titled Troubleshoot Email Delivery Issues with Google Groups and Help Scout, starts by detailing the different reasons why someone may run into delivery issues. It then breaks down the two causes in more detail.

We lead with the least complicated troubleshooting step and then follow up with the second option and a bulleted list of actions to try to fix it:

Troubleshooting article template

4. FAQ

An FAQ page is a knowledge base article that lists common questions around a specific area of your product. For instance, some companies have an FAQ on things like shipping and order issues, payment processing, and account management.

You may consider having a single FAQ or several more minor FAQs for specific product areas.

Here’s a great example of an FAQ page from our Docs site:

The article, Learn about Help Scout Docs, has a series of subheaders, each one dedicated to specific questions readers might have about the product.

FAQ article template

Go forth and create beautiful, impactful knowledge base articles

Knowledge base articles are the first thing that most of your customers will see when it comes to your product. They have a variety of uses:

• They can help educate users on your product.

• They can answer commonly asked questions.

• They can assist when troubleshooting specific issues.

Because of how integral they are to your customer’s experience, it’s very important to pay attention to how you write and structure them.

Create a knowledge base article process that supports your team in writing impactful, informative articles from the start, and then use precise language and a defined structure to ensure that your customers always know where to find answers when they need them.