how to write effective knowledge base articles

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.

This is a chapter in our  Ultimate Guide to Using a Knowledge Base for Self-Service Support . When you're ready, check out the other chapters:

Chapter 1 – Knowledge Base 101: Definition, Types, and Benefits

Chapter 2 – Quick Start Guide to Creating a Knowledge Base

Chapter 3 – Knowledge Base Design Tips for Better Self-Service Support

Chapter 4 – Incredible Knowledge Base Examples That Get It Right

Chapter 5 – Tips & Templates for Writing Great Knowledge Base Articles

Chapter 6 – Creating Knowledge Base Videos: Tips, Tools, and Examples

Chapter 7 – Simple Knowledge Base SEO Tips Anyone Can Follow

Chapter 8 – The Best Knowledge Base Software + How to Choose One

Chapter 9 – Actionable Knowledge Base Metrics to Start Tracking Today

Chapter 10 – Knowledge Base Tips for a Better Customer Experience

Chapter 11 – How to Revamp Your Knowledge Base Architecture

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.

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, and use tools like Grammarly to 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:

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.

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.

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

Title:  About [Feature Name]

Description:  Brief overview description of the product or feature the informational article is about.

Links:  Anchor links to any of the individual topics within the more extensive informational article.

Further reading:  Links to related articles or other content around this specific feature.

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 How to forward conversations , includes two topics, both of which have lists of steps to take to accomplish specific tasks:

How-to article template

Title : How to [task name]

Task:  A description of the task that your readers are looking to accomplish.

Prerequisites (if applicable):  If you have different pricing tiers, this should include information about which products or pricing plans this how-to applies to.

Table of contents (if necessary):  Create anchor links for quick navigating.

Instructions:

Outcome:  What users can expect to happen after completing the steps in the how-to knowledge base article.

Further reading:  Links to related knowledge base articles or how-tos.

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

Title:  Troubleshooting [name of the issue]

Problem:  Brief description of the problem to be solved and the typical reasons why it occurs.

Anchor links to the specific resolutions (if there’s more than one).

Solution 1 (with a bulleted list, if applicable)

Solution 2 (with a bulleted list, if applicable)

Solution 3 (with a bulleted list, if applicable)

Outcome:  Brief description of how to understand if the issue is resolved or if it is still occurring after trying a troubleshooting step.

Further reading:  Links to related articles.

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 , starts with a video that walks through all of the Help Scout Docs product features. Then, there are a series of subheaders, each one dedicated to specific questions readers might have about the product:

FAQ article template

Title:  Frequently Asked Questions about [Product or Feature]

Topic (if applicable):  Brief description of the product or feature that the article pertains to, perhaps including images or an overview video.

Table of contents:  Anchor links to each question that is answered within the FAQ.

Further reading:  Links to related articles, such as how-tos or troubleshooting related to the product

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.

Like what you see? Share with a friend.

Mercer Smith

Mercer is the VP of CX Insights & Community at PartnerHero, a yoga fanatic, and strives to make the world a little bit happier one customer at a time. You can find her at mercenator.com and on Twitter .

Try Help Scout

Learn the platform in less than an hour. Become a power user in less than a day.

9 Simple Hacks to Write Better Knowledge Base Articles

A knowledge base is a set of organized information about your product or service that a reader can go through to learn about said product or service or how to solve related problems. It is usually a collection of articles with images, videos, and text included. 

Knowledge bases can be aimed at internal or external audiences and can serve different purposes.

For example, a software company may have FAQs and download instructions for their customer-facing knowledge base and also have an internal knowledge base for their employees to understand work-related tools and company policy. 

Knowledge bases are used by customer service, customer support, and customer education teams. 

Creating your own knowledge base article can benefit readers as they can find all the information they need in your article. We will walk you through nine tips that can get you through writing an informative, knowledge base article. 

1. Ask the right questions

This first step will prime your article for success. It’s important to take a close look at what you want to say, but more importantly, you need to recognize the needs of your audience and how your information will help your future customers or clients.

Is there a problem that your current customers face that you can help them with? That may be your next topic. Your goal should be to help users find answers to the questions they have about your product or service. 

To write an effective knowledge base article Here are five questions, which will help you develop excellent customer education content :

• What is the goal of the content?
• What are your audience’s expectations and needs?
• What are the processes people currently use?
• What is your audience’s current experience?
• What will resonate with your audience?

They’ll help you pinpoint your audience’s expectations and needs, as well as their current experience. 

2. Pick one idea per article

This might sound a bit like a high school English class, but see if you can also define your thesis statement . 

This will help you narrow down your article and create a specific answer for a specific problem.

Real-life example

For example, Slack doesn’t have a help article on “How to use messages.”

Instead, they target a specific customer need, such as, “Format your messages” or “View all your unread messages.” 

3. Talk with subject matter experts

Understanding the “why” to your article will help you remain focused and pull targeted research. When possible, we suggest working with subject matter experts. 

However, if you need to draft a knowledge base template and you’re not an expert in the field, that’s okay. Interviewing a subject matter expert will help you work around that. 

4. Use headers to break up your content

Once you’ve decided on a specific strategy for your article, it’s time to start painting the picture. With the research you’ve gotten yourself or the information you’ve gathered from your subject matter expert, you can begin to outline your article.

Setting your subheadings (often written in H2) creates the base-structure of your article. They direct the structure and flow of your information and, most importantly, guide readers through your information. 

Take this example from Zendesk :

In their article they do a great job of breaking up their content using simple subheadings.

On longer articles, Zendesk even adds a table of contents at the top of each article.

We’re all guilty of scanning the headers of an article before reading all the way through to make sure it’s something we want to invest our time in. Creating a headline that indicates what information is found below, you are well on your way to getting readers past the title.

5. Focus on your intro 

After you create your headers, you can shift the focus to your intro. Keep this short and sweet, but be sure to include your thesis statement or key message of the article up top.

Your intro doesn’t have to be complicated. Even just a quick one or two-sentence summary can help add clarity for people looking for answers.

6. Kill the curse of knowledge

Always remember that your audience may have no knowledge on the subject matter at hand; you always want to use language that people of all levels of expertise can understand.

In the world of online education, step-by-step guides are an excellent tool to help someone learn something new or get help.

Start with the most basic details of your content area and build from there. If you don’t already, try creating a “Getting Started” guide or article list to help your users get started using. your product quickly.

You can advance to more complicated topics only after you’ve laid a solid foundation. 

7. Add images 

For many, this is the fun part. With your educational content in place, it’s time to add images.

Adding images will improve your content’s performance because, no matter how ‘good’ your content is, it will likely get overlooked without visuals.

And they’re really simple to create:

If your step-by-step guide is showing folks how to download and set up an application, include helpful screenshots of the process to help them visualize your information. 

One thing to note with screenshots is that you need to make sure to keep them up to date .

Screenshots are just the ticket for taking your article from a helpful blog post to a full-blown reference guide, so, they’re well worth the little bit of upkeep that’s required. 

8. Add videos

Embedding videos in your article will also improve your content. Articles with videos often increase viewership more than those without. 

Having a relevant video in your article can increase the value a reader gets from your content and it typically keeps them on your page longer. The more time someone spends on your page, the more familiar they will get with your brand . 

Real life example:

In this example, Privy created a custom video to with their article.

You don’t need to create a Hollywood-level video either.

To start, just record your desktop as you walk through the process.

Here’s a quick video that will show you how:

We recommend using Snagit , for short, quick videos, and Camtasia , for more advanced instructional videos .

9. See if you’re SEO friendly

Now that you’ve written your article, it’s time to make sure your article gets found. Here, we enter the world of Search Engine Optimization (SEO).

You always want to write your content organically and keep your user in mind. However, when all is said and done, you also want to make sure your information gets found on Google (and other search engines).

Because if people can’t find your help, it’s not very helpful.

The best place to start is with keywords.

In an article about building a company app, be aware of what search terms people are plugging into Google when they want to know how to do this. Is it, “building an app,” “how to build an app,” or “developing an app?”

Add important keywords

Fortunately, there are tons of free keyword research tools out there that will tell you what people are typing into Google to find information on your topic. With your primary keywords in hand, be sure to include them in the following areas: 

• Article titles
• Intro paragraph
• Meta descriptions

Be cautious of keyword stuffing though.

For example, once you know which keyword will rank well, don’t stuff it into as many paragraphs as possible in an effort to rank higher. Google will actually penalize you for doing this.

Focus on your meta description

What exactly is the meta description? Think of it as a short blurb that describes what your article is about. This is what we scan when we pull up our search results on Google. It helps people see if the article is worth reading even before they look at your headers.

So, without question, your meta description is important and it needs to include your primary keyword. It answers, “What’s in it for me?” and entices online users to click on your article over anyone else’s work that pops up on Google.  

Include Alt text

Alt text is used to describe the function of an image. This is separate from a caption. People reading your article will be able to read your caption, but not the alt text (unless your image didn’t display for some reason). 

Search engine crawlers are what read your alt text . When Google (and others) crawl your site to index the content, it’ll pick up the alt text on your image and, if it has a popular keyword in it, you have the opportunity to rank higher. 

Write better knowledge base articles today

We love helping content creators include images and videos for better training, tutorials, lessons, and everyday communication.

When you’re ready to turn your next article into an almighty how-to with step-by-step guidelines, screenshots, and video, we’re here to help you bring that to life.

Lizzy Smiley

Marketing Content Writing Specialist at TechSmith. I love my dog and The Office.

• How To Merge Videos
• 3 Reasons Video is the Right Internal Communication Method

Subscribe to TechSmith’s Newsletter

Join over 200,000 people who get actionable tips and expert advice every month in the TechSmith Newsletter.

• Hubspot Blog
• HubSpot.com

Oh no! We couldn't find anything like that.

Try another search, and we'll give it our best shot.

An Easy Guide to Writing Effective Knowledge Base Articles [+ Templates]

Published: June 23, 2022

Raise your hand if you like waiting on hold for customer service?

When faced with calling customer service versus finding the answer ourselves, we'd much rather solve problems on our own.

Having a webiste with a knowledge base empowers customers to reslove their issue without needing to contact customer service. This isn't exactly the best news for someone in customer service , but it doesn't mean your job is becoming obsolete. Rather, it's evolving to fit the changing needs of customers.

Creating an effective knowledge base is a big undertaking. We've put together a handy knowledge base template to take the guess work out of helping customers find the resources they need.

What Is a Knowledge Base?

Knowledge bases are online databases that store information about a specific company, its products or services, or related industry topics. The data is either collected and stored through artificial intelligence or manually uploaded by expert contributors.

A company's knowledge base can provide valuable information to customers, prospects, and even employees. You can include important facts about each department, directions for product or service usage, FAQs, and original content that can provide in-depth solutions.

HubSpot's knowledge base helps us better serve and delight our customers by helping them access the solutions they need 24/7. Knowledge bases have also decreased the need for customers to search for questions on search engines. They can simply search the same question on your company's knowledge base, knowing the answer will exist in relation to the appropriate product or service.

Knowledge Base Article

A knowledge base article provides information about a specific product or service and acts as a guide to help users solve common problems. They often provide step-by-step instructions on how to use the product and all of its features.

These articles also don’t have to be limited to written content. They can come in the form of an infographic, video, gif, or other visual aids.

Knowledge base articles allow users to find the information on their own and resolve issues at their own pace while also freeing up time for your customer service agents since they won’t have to answer the same, repetitive questions. Common types of knowledge base articles include:

• Troubleshooting guides
• Tool descriptions
• Informational
• Industry guides

It's evident knowledge bases are an invaluable resource to both your company and your customers. But, how do you go about creating one?

How to Write a Knowledge Base Article

When a customer is looking for a solution to a problem, your knowledge base should make it as easy as possible to find answers. It's important that your knowledge base articles not only contain the solution that the customer is looking for, but is also formatted in a way that makes the answer clear and obvious. When writing new articles for your knowledge base, check out this guide for writing effective knowledge base articles.

Featured Resource: Knowledge Base Article Template

1. Select simple titles using target keywords.

Knowledge bases are mainly for your customers and prospects, and not internal stakeholders. Thus, the language being used in the titles and articles should be simple, clear, and concise.

When choosing titles, put yourself into the customer's shoes. What kinds of topics would they search for? What's their expected difficulty level in terms of knowledge on the product or service? Write titles based on this information. It's also helpful to use search-engine-optimized keywords in the title to attract more search volume.

The most common titles start with:

• How to [insert topic]
• Setting up [insert topic]
• Using [insert topic]
• Getting started with [insert topic]

It's also helpful to use search-engine-optimized keywords in the title to attract more search volume. In addition to the list above you can also title articles based on the actions your customers will be taking. For example you could write “Creating your first video” or “Installing a widget.”

2. Only have one article per specific topic.

It's inefficient to have more than one article for the same topic. Not only does this split traffic between multiple articles, but it can get confusing for customers if they have to keep switching back and forth between multiple pages to find all the information they need.

If you gain more information on a topic, do a keyword search to see if there are any articles with similar keywords. If so, you can update the existing article with more information.

This will make the article more all-encompassing so readers can gain all the information they need from a single source.

If you’d like to cover a related topic, you can link to it in the existing article. We’ll discuss covering related topics later on in this post.

3. Categorize articles for easier browsing.

Knowledge bases aren't just for searching. While many customers will search specific questions to solve problems, they may also use the database as a way to browse through related topics. This means your articles should be categorized by sections and subsections.

For example, on HubSpot's knowledge base, you can search by HubSpot product, the type of resource, or a variety of topics, such as Blog, Dashboard, Emails, Integrations, and Sales Templates.

Pinterest's knowledge base for business (pictured above) groups articles with easy categories like Create a shop, Advertise, and Create content to help users quickly identify the articles of interest.

Using categorieskeeps the knowledge base organized and ensures every article has a place and a purpose.

4. Include a table of contents, if needed.

Sometimes, an article can get pretty long, especially if you've updated it with added information. Dedicated customers will scroll until the end when they want an in-depth, complete understanding of the problem and solution.

5. Describe the problem, if applicable.

Start off the article by stating what the problem is, for scenarios that are problem-solution based. Not all knowledge base articles are meant to solve problems; some may just explain how to complete a task. In those cases, you can skip this step.

Identify what the symptoms of the problem are to clearly relay what customers should be looking for. For example, list what error messages should be popping up if the problem does exist. You want to use basic language and make it as clear and concise as possible. The briefer this section is, the better, as people reading will likely be looking to get to the steps to solve their problem quickly.

6. Relay the steps to accomplish the task at hand.

After stating the problem, you should immediately jump into showing readers how they can solve the problem. Lay out this section in easy-to-read steps that can be read and followed in succession. You want to make sure the steps actually solve the problem they claim to solve. If the problem can't quite be solved, the steps can help eliminate potential causes or reveal what the root problem is.

You'll want to lay out steps specifically for articles that are solving problems or showing how to accomplish a task. For comprehensive guides, you might not need to utilize steps. Instead, you can divide up the text by explaining different aspects under separate headers.

7. Announce what the solution should be.

You should end the article by describing what the solution is. After all, since not every problem can be completely resolved, the solution may be an improvement of the problem or an update of a product to avoid a former glitch. If needed, you can explain why a permanent solution couldn't be attained but that the solution laid out is the best case scenario for improving their situation.

If there's no direct solution, or if the end result is self-explanatory, this step may not be needed. Instead, you can reiterate in the final step or paragraph that you've reached the end and that the task has been achieved.

8. Offer other article links for further reading.

You never know if you've completely exhausted a topic for interested readers. Rather than making them browse through related articles on their own, you can link some of your other articles at the bottom or side of the article.

This will help customers gain a more well-rounded education on the topic at hand. And, it helps get more eyes onto the articles you and your team worked hard to create. The more your readers use your knowledge base, the more they'll trust your organization as a source of accurate information.

These steps can help you create knowledge base articles that are effective and clear. However, not every article will be structured in the same format. Articles can vary in layout and design depending on the solution they're providing.

9. Show, not tell.

When trying to explain a concept or deliver instructions, visual aids can work wonders to communicate your ideas. This is especially true when you’re trying to explain a complicated topic.

Rather than just posting a wall of text instructions, consider using photos, charts, video and other media to help the reader gain understanding. This method can be super helpful when describing a multi-step process.

Semrush uses a combination of photos and gifs to walk readers through checking their online visibility. This way readers get a step-by-step visual breakdown showing how to complete the task.

Words are great, but can easily be misinterpreted. Showing users how to solve their issue rather than just telling them will help them follow along and accomplish their task.

10. Ask for feedback.

While you may think you have the best knowledge base out, you should always strive to make it better. Who better to help you with that than the people who use it?

Each article should have a spot where users can submit their feedback. The CTA should be as simple as possible and not require a heavy lift on the user’s behalf. Instead you can ask them a simple question like “Was this article helpful?” or “Did this article resolve your issue?” with a simple yes or no option response.

Semrush, pictured above, uses a simple thumbs up or thumbs down symbol to solicit user feedback. It’s quick and effective. For those that answer “no,” you can add a text box pop up for users to further explain what went wrong. Understanding the user’s pain points and making adjustments will improve user experience and the effectiveness of your knowledge base.

Knowledge Base Article Templates

The structure of a knowledge base article plays a major role in the piece's clarity and appeal. Customers are looking for specific and concise answers, and don't want to waste time scrolling through an essay to find it. Utilizing the common knowledge base article templates can play an instrumental role in determining the effectiveness of your self-service customer support.

Image Source

How-to articles are typically brief. They show you exactly what steps to take to complete a specific task or perform a certain function. This is usually the type of knowledge base article that helps visitors solve problems they're facing with their products.

How to [Name of Task]

Applies to [Your Appropriate Products]

[Brief Description of Problem, if Needed]

[Brief Description of Solution, if Needed]

Related Articles:

[Three to six articles with links]

FAQ articles include a list of questions about the same, related topic on a single page. This includes general and tool-specific questions. They're usually all listed at the top in a table of contents with anchor links that allow you to jump down the article to the specific question you need to be answered.

[Topic Name]: Frequently Asked Questions

[Brief Description of Topic]

Table of Contents:

[Question 1]

[Question 2]

[Section 1]

[Section 2]

[Tool-Specific Category 1]

[Tool-Specific Category 2]

3. Tool Description

Tool description articles give a short description of what a specific tool or function is. Rather than answering questions or laying out steps, it tells you exactly how something works.

[Tool or Function]

[Brief Introduction of Tool or Function]

[Description of Tool]

[Final Tips/Information to Note about the Tool]

4. User Guide

User guide articles are long, comprehensive guides that cover an entire tool or function. Similar to an instruction manual, they include information on using every single feature to give you a well-rounded education on the tool or function.

A Guide to [Tool or Function]

[Main Feature 1: Description]

• [Sub-Feature 1: Description]
• [Sub-Feature 2: Description]
• [Sub-Feature 3: Description]

[Main Feature 2: Description]

5. Quick Answers

Quick answer articles highly resemble user guide articles. They, too, are long, comprehensive guides that cover an entire tool or function. However, the difference is that quick answer articles include a table of contents in the form of anchor links -- like FAQ articles -- that allow you to jump down the article to the specific topic you want to learn more about.

[Tool-Specific Category 1]:

[Tool-Specific Category 3]

[Tool Specific Category 1]:

[Description]

It's always helpful to include screenshots as examples for any tools, functions, steps, or descriptions that may be confusing to explain in words. Also, by showing your text alongside a visual, readers can follow along on their own product while reading your knowledge base and compare their progress.

Create Your Knowledge Base

Knowledge bases empower customers with the information they need to resolve issues and allows your service team to have some variety in their work day. Keep your articles clear, descriptive, easy to navigate, add helpful visual aids and you'll be sure produce resource that delights customers.

Editor's note: This article was originally published in March 2019 and has been updated for comprehensiveness.

Don't forget to share this post!

Related articles.

How to Create Technical Documentation in 6 Easy Steps [+ Examples]

What is a Knowledge Manager? (+ Job Description and Responsibilities)

What Is a Knowledge Base, and Why Do You Need One? [Definition]

18 Best Knowledge Management Software

How to Create a Forum Website for Discussion & Customer Service

This Data Shows Why Brands Need a Knowledge Base in 2020

Do Customers More Frequently Use Chat or Phone Support? [HubSpot Data]

HubSpot's Customer Support Experts on How to Develop a Service Strategy for Social Media

5 Things That Distinguish a Knowledge Base From a Company Blog

A free knowledge base article template (+4 other free templates).

Subscribe for blog updates

Thank you for subscribing!

OOPS! something went wrong try after sometime

How to Write an Effective Knowledge Base Article

According to Statista, 88% of customers expect companies to offer an online self-service portal. Creating a great knowledge base article is the first step to promoting self-service. But how do you create a great knowledge base article? How do you choose which questions need to be answered in your knowledge base? And how do you measure if your knowledge base is successfully helping customers get quick answers, while unburdening your support team? Here’s a quick guide for you to write different types of knowledge base articles and help your customers find answers without any agent assistance.

What is a knowledge base?

A help desk knowledge base is a repository of information about your product or service. This curated resource portal can be leveraged to find answers to product-related issues or may contain a step-by-step guide t o learn how to use the product or service. A modern knowledge base will support multiple formats of learning, including solution articles or FAQs, product manuals, tutorials, videos, and troubleshooting guides, all categorized into distinct themes or folders. It acts as the source of truth for the product or service to its stakeholders i.e. customers, employees, and partners. 

A knowledge base may be a part of a company’s self-service portal or may be a section on its homepage. For easy navigation, it’s advisable to add a search functionality that helps customers type in their queries to get directed to relevant resources right away.

Advantages of creating an effective knowledge base article

According to Forrester, self-service yields a better CSAT rating as compared to a virtual agent interaction. That’s not all. A knowledge base is equally useful for your customer support agents as much as it is for your customers. Your support agents can refer to the internal knowledge base articles to answer any customer queries quickly instead of reaching out to someone for guidance or trying multiple solutions. On the other hand, your customers can search for answers to common questions in the knowledge base instead of contacting your support team and waiting for a reply.

The end-to-end guide to an effective knowledge base article

It doesn’t matter what the size of your company is or the kind of industry you work for, getting started with the creation of a knowledge base is easy. You can even make use of a knowledge base software to choose a template of your choice, create the table of contents using search optimized article titles, and provide structured solutions to commonly raised concerns.

Remember: Your customers should just a web search away to your knowledge base articles.

There are no predefined rules to creating the best knowledge base article. You fail, learn and repeat. We have written hundreds of articles for our knowledge base, and it is used by over 150,000 customers. Having leveraged SEO to our advantage, we are still experimenting with the way we optimize our articles so they are easily searchable.

Here’s a look at what worked for us (and a little bit of what hasn’t).

Getting started with a knowledge base article:

• Answer FAQs
• Onboard users

Before writing the knowledge base article:

• Understand user pain-points
• Write for the average user
• Cater to different kinds of learners
• Eliminate the writer bias

While writing the knowledge base article:

• Tips to follow while writing the article

After writing the knowledge base article:

• Interlink articles
• Gather feedback

When you are creating your knowledge base for the first time, you will have a lot of topics to choose from. Start by collaborating with your customer support team to collect and analyze customer feedback. Enable your team to leverage these insights to deliver an exceptional customer experience by creating help articles that encompass step-by-step instructions to perform tasks in no time. You can even save time on creating your articles by creating knowledge base article templates for How to, User guide, FAQs, and more. 

One of the following techniques (or maybe both) should help you identify and prioritise which KBase articles to create first knowledge base:

What are the questions that have been frequently asked by your customers to your customer support team ?

If you are not sure, browse through your support tickets from the past month (or week, if the ticket volume is huge). If that doesn’t give you enough information, find out what your customers are searching for by looking at your search terms in Google Analytics.

Tip: Connect your support portal to Google Analytics and get insights

Enlist these identified keywords and search terms. The next step is to start creating and adding these articles to your knowledge base.

Here’s a way to approach the creation of help articles. Write down the top 10 things your customers should be doing for them to see value in your product. Should they invite their team to use it? Should they import data from their previous system?

Collaborate with subject matter experts to write support articles that can assist your users in using the product/service to their advantage. Organize them based on the key features so that customers who visit your support portal can find them easily. You can also create a seamless customer experience for users visiting your support portal by creating playlists. This gives you an opportunity to categorize articles and let your customers transition to the next relevant article without the need to exit the portal.

While answering FAQs will help your agents immediately, writing articles that help onboard new users will help you in the long term. We started out by writing basic FAQs and now, we write articles for every new feature that gets launched.

You have to make sure you have researched what you need to achieve before even getting started with a knowledge base article. Take time to understand and confirm the topics you should write about, identify customer pain points and determine the structure of your article.

• Understand user pain points.

Before writing a tutorial, follow the step-by-step instructions yourself. You may even ask a couple more people to try the same. Take notes as and when you get stuck or about the steps that got others confused. Did something result in a delayed response? Do you need to rectify any of these aforementioned steps?

You might have a lot of tickets recorded on your helpdesk. Go through related tickets and find out where your users face issues. This approach will help you anticipate user pain points and questions, and present a way to eliminate or avoid these using troubleshooting guides. With the right software, your help desk can categorize tickets based on the queries raised, further reducing human effort.

You are not writing your knowledge base articles for just one kind of customer. What comes easy for a power user may be too complex for an average user. If you feel like you need to explain more to a newly onboarded customer (wrt the information that a power user would like), split the use-case into multiple articles and link them to the original longer article . This way, the article written for the average user doesn’t need to have too much information.

For example, while explaining about the social tab in Freshdesk, instead of just telling users ‘You can search Twitter using the social tab’, we wrote a separate article on how to search on Twitter (that a power user wouldn’t need) and linked it to the original one.

Different people learn differently. Some like to learn using images and videos while some prefer a step-by-step manual to get started. You need to put yourself in the shoes of the customer to determine the format and the kind of resources that need to be shared using the article. Figure out the sufficient number of screenshots that make the process self-explanatory. Based on the customer behavior, you may also determine if it’s a better idea to incorporate a video instead. You may even add a video at the end of every article.

Take Wistia’s FAQ section for example. Even though they’re a video-hosting company, they don’t fill the entire page with videos without text.

Note: We experimented with presentations and GIFs as a medium, but found that people need a quick solution and don’t wait to watch the different steps in the animation.

You should not let your exposure to customer problems affect the article in a negative way. If you actively support your customers, you are likely to remember all the problems customers face as far as the features are concerned. If you are a tech writer, you are also likely to remember the step-by-step demo you received from the product manager.

Your article about a product feature should neither be a detailed explanation of the UI nor a mini-FAQ. It should be a mix of both. This allows users to understand and learn about the feature and find an effective solution to specific problems.

Here’s an article on SSO on our support portal to help our users understand remote authentication and address common user problems that may involve them getting locked out of their account.

Now that you’ve figured out what you should be writing about and what points you should get across, it’s time to actually write the articles. Make sure you stick to the basics and actually follow through on your plans.

1) Talk like your users talk

Do not use over-the-top words or technical jargon in your articles. Find out what customers call the feature you are writing about (use search terms in GA or by reading tickets). Use those words in the article, headings, and subheadings to help them understand your article easily.

2) Be straightforward.

Your articles need to be easy to scan through and understandable in just one read. You can create tutorials in a way that makes them easy to consume. If you want to improve customer experience, personalize the template, not the content (take a cue from Amazon).

3) Feature trumps benefits

When you write on a support portal, remember that you are not trying to sell. A solution article is written to help, not to convince. So your articles should talk more about the nuances of the features and not cover the benefits of using your product .

4) Treat every article as a mini-onboarding process

Start by explaining the feature in simple words. Then, use an example to walk the customer through the product interface and let them know what happens once they follow these instructions. This way, even if the setup process is elaborate, users will follow it through till the end.

5) Bullets and tables are your best friends

Needless to say, formatting solution articles is extremely important. Carefully choose your headers and subtitles. Structure your articles using bullet points and arrange your content using different sections. You may even make the action items bold in each step so it’s easy for readers to skim through your content.

6) Always state the prerequisites

Don’t make it hard for users to find out the limitations of a product . If your app doesn’t run on IE, say it. If this feature is available in the highest plan only, say it. You will save yourself from unnecessary grievances or concerns by being upfront about your services .

7) Nothing is too obvious

Don’t leave out even the tiniest of details assuming that it’s obvious. Use a tabular form or create annotated screenshots when you want to explain multiple little things without making the article too long.

8) Do not sell.

Selling or upselling in support articles is like selling a support ticket (not recommended).

You’ve finally finished writing your article. You can now move on to the next task and forget about this one, right? Nope.

You are not done writing a support article once it’s published. You have to make sure that it is useful, that it’s updated from time to time and it serves the purpose of helping your customers resolve their issues by themselves.

Go through the article you had just written one more time and find out if you can embed any other solution articles. Repeat the same exercise for the other related articles and provide links to the new article.

For example, if your new article talks about plans and billing, you can link it to the one about payment options. This helps readers navigate easily (even if they land up there by mistake) and it increases the chances of the article being found on search engines.

• Actively listen to feedback and improve

A few days after your article is published, you can check if your article is actually helping your agents and customers. Has it reduced the number of tickets for this feature? Are other agents using this article to support their answers? If not, why?

Here’s a way we made life simple for our support team. Freshdesk’s knowledge base has a small survey at the end of every article. Every negative feedback gets converted into a ticket in the helpdesk in which the author is added as a viewer. This way, the author can quickly update the article based on the feedback received.

Extend KBase to AI Chatbots

Integrate your knowledge base with your AI chatbot to automate FAQs for your customers. Chatbots offer self-service through conversation, reducing the effort of searching for answers in your knowledge base.

Smart chatbots learn from every customer interaction and offer intent-specific answers by pulling information from your knowledge base directly. Not just that, chatbots even go above and beyond to inform you of the gaps in your information and signal the scope for improvement of your answers.

Your checklist for writing a knowledge base article

Here are the steps you need to follow to write a knowledge base article:

• Determine the topics that you need to cover
• Structure the articles in an easily consumable format
• Write the articles with the average user in mind
• Add screenshots and videos especially when you explain something complex
• Be detailed as well as specific to help all kinds of users
• Format your articles
• Interlink them
• Get feedback from readers and improve them

A knowledge base article is perfected over time as you update it based on the feedback you receive from readers and support agents.

The perfect article also differs from business to business. You can follow this article to get started with the first few knowledge base articles, but once you get accustomed to the workflow, you can experiment and figure out what suits your customers’ needs. Even if you cannot see the effects of the articles on your users right away, it will be helpful to your agents from day 1. It is also a great way for new agents to get up to speed with your product/service.

Here are some of the tools we use to create our knowledge base content:

• Google docs – to collaborate with multiple stakeholders
• Freshdesk – as a knowledge base provider
• Quicktime – to record screencasts
• Sketch – to annotate screenshots and create graphics
• Grammarly – to spell check the articles

Your turn now.

What are some of the things that worked with your knowledge base articles? What are some articles that helped you out as a user? What are some best practices for writing a knowledge base article that you’ve learned from your experience?

Share with us in the comments below.

Originally published on Jun 1, 2018. Updated on February 16, 2022.

Related Posts

The art of writing awesome emails that customers love, how to keep support agents engaged and motivated.

How to Write Effective Knowledge Base Articles [With Examples]

Writing great knowledge base articles isn’t as hard as you think. Learn how to craft first-rate content that empowers customers to help themselves.

Last Updated

February 26 2021

The key to writing great knowledge base articles is ensuring the content is clear, engaging, and informative for your end users.

The good news is that crafting awesome content for your knowledge base isn’t nearly as complicated as many people think. 

With the right approach and a dash of know-how, you can author articles to improve your customer's and employee's experience with minimal stress.

In this article, we’ll run-through eight best practices for creating great help content as well as share several examples to inspire your own.

How to Write Effective Knowledge Base Articles

When you boil it down, the difference between ineffective help content and brilliant help content is this: Brilliant help-content empowers users to accomplish whatever they set out to do.

The following 8 steps will ensure your knowledge base content helps users get the job done:

• Understand user pain points
• Assume reader's know nothing
• Make it easy to skim
• Keep it succinct
• Write plain titles
• Hone your voice
• Internally link
• Test and improve processes

Understand User Pain Points

There’s nothing more essential for writing great knowledge base content than understanding why your users are looking for help in the first place. Because figuring out what questions your customers are asking and identifying common themes directs you to create the most relevant content.

The good thing here is that most business owners already have a decent idea about where their users are getting stuck. But if you’re not sure, have a rummage in these 4 places:

• Ticketing system : Support calls, chats, and emails can be a rich source of customer frustrations.
• Support agents : They have valuable insight into customer pain points - make a list of the most frequent customer complaints they deal with.
• Social media : Customers frequently go to social media for help or to express their dissatisfaction - review your messages, mentions, and hashtags.
• Community forums : Check out what users are asking each other and where they’re running into difficulties.

Assume Reader’s Know Nothing

One of the worst things that can happen in a knowledge base is that your writing confuses your reader by talking about things they don’t understand.

To avoid this, assume your readers know zilch. Compose your articles as if you were communicating with an absolute beginner. 

You don’t need to dumb things down per se - think more along the lines of swapping out technical jargon and explaining difficult concepts in simple language.

For example, before explaining how customers can get started segmenting their email lists, the marketing automation platform Mailchimp defines several key terms new users might not be familiar with.

Bringing readers up to speed like this ensures that they won’t get lost further down the line when more complex problems are introduced.

Another habit that'll torpedo your articles is mentioning ‘how-tos’ in passing. For example, let’s suppose a reader wants to edit their photos using a piece of software

Which of these would be a more helpful solution?

• After connecting your camera, import your photos
• After connecting your camera, click Menu > File > Add Photos > Import > Import all

Number one assumes the reader is already familiar with how to import photos. Number two, on the other hand, works for both those who know and those who don’t know how to complete the task.

The takeaway? Make zero assumptions about what the reader knows - no matter how straightforward the task or concept may be. More advanced users will simply hop over basic details, but less experienced users will run into mountains of difficulty if they’re missing.

Make it Easy to Skim

Making no assumptions about what the reader knows means some of your articles may end up being quite lengthy. And that’s not necessarily a bad thing.

But with 31% of customers expecting instant online help, and 40% of them expect to receive assistance in less than 5 minutes - you want to make it as easy as possible for people to find what they need.

The key with extended articles is to break them up under appropriate headings, subheadings, and bullet points so users don’t feel intimidated by a colossal wall of text.

For example, look at how Shipt splits up longer-form content to make it more digestible. When initially visiting their knowledge base, you're presented with several popular topics as well as frequently asked questions.

When clicking on one of these FAQs, you're brought to a separate page that's further broken down into subtopics as seen in the screenshot below.

By making use of a variety of headings, spacings, bolded text, and bullet points, the information instantly becomes more approachable.

To do this in your articles:

• Start by writing out all the ideas you’re going to include
• Bundle related ideas together under common headings
• Order headings in a way that makes logical sense
• Write your paragraphs under each heading with no more than 2-3 sentences per paragraph

Once you’ve got a solid structure in place, it’s also wise to add a table of contents with anchor links to allow users to navigate directly to the section they need. This is especially handy for more advanced folk who might want to skip the entry-level stuff.

For example, Zoominfo does an awesome job of making it easy for users to navigate to the relevant section without the need to scroll up and down the page.

In short, structuring your articles for skimming increases your KB’s usability, helps users better understand your message, and ultimately resolve their problems faster.

Keep It Succinct

With all this talk about extended articles, it’s important to remember that length is not the goal here, it’s simply an occasional side effect of creating comprehensive guides. The truth is that the more concise you can make your article, the better.

Think about it: if your customer is trying to get themselves out of a jam, they don’t want to sift through mountains of superfluous information. Instead, they want the relevant knowledge they need to solve their problem, and not one word more.

That means you must become a ruthless editor. Strive to eliminate unnecessary information that doesn’t add to the issue at hand. Shorten your intros. Chop wordy paragraphs down to size. As a rule of thumb, if you’re unsure if something is relevant or not, it probably isn’t.

Where appropriate, make use of media for greater clarity too. Screenshots & GIFs can go a long way to helping users absorb information more quickly when deployed alongside text. Giphy Capture and LightShot for Chrome are two great tools to accomplish this.

However, be careful using video for solving problems or errors. While videos are good for general overviews and introductions - they’re not as capable of zeroing in on the specifics that your customer is looking for. People in a rush will be forced to watch an entire video to get the one nugget of wisdom they needed.

If you do use video, make sure to timestamp it. Plus, include a text version alongside to make it more efficient and consumable for your time-starved users. Remember, keeping things to the point is the name of the game.

Write Plain Titles

Knowledge bases aren’t blogs, so there’s no need to try and hook the reader’s attention. Users are already looking for your help anyway.

Instead, craft simple titles that convey what problem your article addresses. Ask the question: “What would my users search for when looking for this information?” and when answering aim for clarity over creativity.

Keep in mind that people typically search using basic keywords - “how to insert images and videos becomes ‘insert images and videos” - so model your titles around the keyword phrases.

Using active verbs is a good strategy for kicking off the title of your articles. Some examples are:

• “Launching…”
• “Setting up…”
• “Creating…”
• “Getting started…”

Alternatively, you can simply state what topic the article is about for example, “Overview: Article Templates”. As long as it’s crystal clear what your article is about, you can’t go too far wrong.

As you can see from our knowledge base - none of the titles on display are flashy. Instead, they’re clear cut - just the way they should be.

Hone Your Voice

As linguist Steven Pinker points out in his book ‘The Sense of Style’, smart folks often shun simplicity in an attempt to prove their intelligence. However, as Pinker reveals, using flowery language only makes others think they’re poor communicators.

And your knowledge base is the exact same. People won’t be impressed by your high command of the written word if it’s distracting them from getting what they came for.

So, here’s 7 tips to keep things on point:

• Put your faith in plain language
• Use the active voice
• Use common, familiar words
• Use a single term for each concept across all your articles
• Write as though you’re talking to just one person (ideally, your buyer persona)
• Avoid humor when troubleshooting errors (a little humor is fine for non-troubleshooting articles)
• Keep it to the point - spreading ideas over too many words will lose your reader
• Always keep your reader’s goals at the top of your mind

The ultimate goal is to make your writing engaging, but without allowing your message to become lost amongst a sea of ‘brand personality’ or unnecessarily complex language.

Two tools that can whip your copy into shape are Grammarly (awesome for spell checking and finding better phrasings) and the Hemmingway Editor which will make your writing bold and clear.

Link to Related Content

So don’t link to every article that’s remotely related to the topic at hand. Instead, use links only when they’ll nudge users towards the next logical piece of content.

( Note : As we'll discuss in the next step, you'll be able to figure out the logical pieces by analyzing data from your knowledge base analytics as well as collecting feedback from your support agents. )

Constantly Improve Your Process

The perfect knowledge base doesn’t exist. All great knowledge bases became that way precisely because they committed to the continuous improvement of their content.

How do they do it? Through data and feedback.

A good knowledge base software will provide analytics that let you discover things like:

• How your content is performing over time
• What topics users are searching for
• What topics people are consuming most
• Which articles need to be improved

Using such information, you can double down on what’s working and ease up on what’s not. Over time, you’ll build a powerful collection of articles that your audience will thank you for.

It’s worth mentioning that the benefits of analytics go beyond just improving your articles. Support data is a great source of insight into how customers are thinking and feeling. That means it can also help you build a better product, refine your sales process, or inform your marketing strategy too. 

Just think about it: if lots of users are searching for “how do I integrate with (insert tool)” you can feed that information back into your dev teams and build a solution that your customers want.

That means that while your writing is giving users a better experience, how they’re interacting with your content is giving your business valuable feedback about how to improve. Talk about a win-win.

Examples of Excellent Knowledge Base Articles

Okay, now that you have an idea on how to write effective articles that will support your end-users, let's look at some great knowledge base examples from real companies to see how they are implementing these same practices. 

Visual Overview of the HootSuite Dashboard (@Hootsuite)

Hootsuite’s guide on how to use their dashboard is a perfect example of how to ace a knowledge base article. A short introduction leads into a video overview of the topic which is supported by a well thought out article beneath. Complete with screenshots and handy links for more information makes learning the dashboard features a breeze.

McAfee WebAdvisor Blocking RMS Reports (@RMS Cloud)

RMS has created a fantastic page on how to stop McAfee from blocking RMS reports. Notice the skimmable layout, clear step-by-step instructions, large text, and handy visual guide at the end. And does it work? Well, with lots of articles like this, RMS cloud has been able to resolve 50-75% of their day to day support requests via their knowledge base.

Conversion Tracking for Websites (@Twitter)

Twitter’s monster article on how to set up conversion tracking is a great example of how to structure longer-form content. The spacing, use of headings, annotated screenshots and ever-present navigation mean users can quickly locate, extract, and implement the knowledge they came for. 

How to Preview & Compare Courses (@Udemy)

The shortest article on the list, but no less impressive, is Udemy’s piece on how to compare and preview courses. It’s simple, to the point, and teaches exactly what its title says. A welcome reminder of the need to keep things concise.

How to Navigate Estimate Rocket (@Estimate Rocket)

Estimate Rocket breaks down exactly how to navigate its SaaS tool in this brilliant article.  Each panel is dissected and explained in plain language with the help of a screenshot so users know exactly what’s being said. The writing is clear and concise, the headings are well spaced out and there’s a link to contact live support in case you didn’t get the answer you were looking for.

Setting Up Your Online Store (@Shopify)

It’s bullet-points galore in Shopify’s ‘setting up your online store’ article which makes getting started with their platform a walk in the park. The use of bolding alongside clear headings is particularly effective to help you skim through the article. And if that wasn’t enough, they included anchor links at the top for maximum efficiency.

How to Make A Collage (@Collage)

Ecommerce company Collage makes it dead easy for their customers to create their own personalized photo collage with this awesome page. It’s a great example of how you don’t need to go overboard with fancy graphics or complicated design. Sometimes it’s better to pair things back and let your help content do what it does best.

Wrapping Up

Writing good knowledge base articles can be a challenge at first. But with practice and a little elbow grease, you’ll soon be whipping up articles that your customers adore.

Start with the easy stuff. Begin writing just a few articles on uncomplicated topics. As you grow in confidence and skills, you’ll be better equipped to tackle complex articles without pulling your hair out.

Like Rome, no great knowledge base was built in a day. So don’t try and rush things. Instead, approach your article writing one step at a time. Focus on quality, stay organized, stay consistent, and stay patient. 

Trust the process and you’ll reap rewards sooner than you think.

More Blog Posts

Enjoyed this article? Check out our favorites

4 Bulletproof UX-Hacks To Skyrocket Your Knowledge Base

6 Simple Tricks to Make Your Knowledge Base Searchable

Case Studies

Our Case Studies

Some of the best case studies to improve your knowledge base

How FlowWright Revolutionized its Documentation Process and Reduced Support ...

This Chat App Reduced Internal Onboarding By An Unbelievable 40%!...

How Helpjuice Helped Royal Dance Conservatory Onboard Employees 2-3 Times Fa...

Start your 14-day free trial.

Join over 1000+ companies already growing with Helpjuice.

• Knowledge Management
• Knowledge base Software
• Technical Documentation
• API Documentation
• Customer Support
• Best Practices
• Product Updates
• Product Engineering

Need an awesome Knowledge base?

We'll show you how to build a knowledge base (public or private) in minutes.

How to Write an Incredible Knowledge Base Article

Category: Knowledge Base Software

Last updated on Dec 14, 2022

The usability of your knowledge base depends on how you organize information and how clear your articles are.

Putting things in the right place is the key to better self-service in customer care. That means you should deliver valuable content, in small chunks, using accessible terminology.

Learning to create helpful knowledge base articles takes time and practice. You need to develop your skills to write content that’s engaging, clear, and informative at the same time.

Every article should be easy to follow, to make things as comfortable as possible for your users, no matter how familiar they are with your product.

Your knowledge base article should also be written in the right tone of voice—professional, but friendly.

The only way to achieve the best results is by mixing a relevant message with sharp writing techniques. And that’s not something you can craft overnight. You need to test your content and improve it on a regular basis.

That’s why we’ve put together the ultimate guide on how to write a knowledge base article to improve customer support.

Before you start writing a knowledge base article

Write a knowledge base article to reflect your objectives: you need to provide your clients with an excellent customer experience on your website, increase traffic, and improve customer retention.  

To make things easier, you need a strategy in place . What you do at this stage is vital for how you develop your content.

1. Fundamentals

Define the basics : How your knowledge base fits into your customer support and how you’ll develop it in time.

What topics are you going to cover in your articles?

How to write a knowledge base article better to outshine your competitors?

Defining the scope of your project can help you build a solid foundation for it. As you set a budget and some realistic objectives, you create a picture that gets clearer with every new detail. And, your ideas for quality content become easier.

2. Priorities

Write a knowledge base article with a balanced mix between your expertise and what the audience needs. You must go beyond your competencies and see how to put your knowledge to work.

You’re the expert, but what the customer wants to hear is equally crucial to the success of your knowledge base software.

Implement a knowledge base system today and reduce your customer support cost by 67%

When you prioritize, you decide what articles to write first, based on the problems your customers deal with on a regular basis. You choose the topic area that makes a difference for your users, and build content on subjects of interest.

3. Audience

Write a knowledge base article with your public in mind – the people who use your software.

As with marketing, you should build a persona – your average client. This way, you get to know the people you’re really speaking to.

When you write a knowledge base article, remember, you’re talking to a public that already knows you. You don’t have to describe your products. Your mission is to teach your clients how to get the most out of what they purchased.

Build a content plan

Getting ideas for incredible articles is the hardest part of writing. That’s why you need to plan your content ahead. This method helps you to create content on a regular basis and makes sure you cover all the essential topics.

A content plan puts your ideas in order: topics to include and subjects to develop at every step of the project.  

How do you know what to start with?

Google can be a helpful guide. Search for the hot topics in the industry and see which results perform the best.

You can also use previous discussions with your clients and tickets you’ve solved in the past, to identify interesting topics for a truly comprehensive knowledge base solution.

Create a different article for every pain point you identify. This way, you’ll give accurate answers to your users, without getting lost in too many details.

Use specific titles

The titles you give your articles should be specific — what question you answer or what problem you solve.

You don’t use your company’s knowledge base to sell, so focus on usability, not drawing attention or hooking new clients.

The title doesn’t have to be eye-catching. It must tell your public what’s in your article. Facebook’s Help Center , for example, uses four types of titles:

• Closed questions : “ Can I like or share videos on the Facebook video for TV app? ” or “ What are my privacy shortcuts? “
• Problems : “ I can’t add a video. ” or “ My privacy settings are not working correctly. “
• How questions : “ How do I view my information on Facebook? ” or “ How do I choose what I get notifications about? “
• Descriptive title (the exact phrase of the process you describe): “ Cost per optimization event ” or “ Friending. “

These titles are optimised, making navigation easy for any user, new or already used to your knowledge base.

There are many more options than these four types of titles. Google Support, for example, has adopted the word “About” for many of the articles in its knowledge base: “ About manual CPC bidding “, or “ About campaign budgets “.

You can also work with words such as “ Setting up “, “ Creating “, “ Getting started “, or “ Using “, depending on your activity.

Here are some examples from MailChimp: “ Set Up MailChimp Subscribe for iPad “, “ Create a landing page “, or “ Use Button Content Blocks “.

The “ How to ” title can also be a smart choice. It explains what each article is about with minimum words.

Keep intros short

It’s always tricky to craft the perfect introduction, especially when you have to draw attention and to convince the reader to keep reading. But that’s not the case when you write a knowledge base article.

Here, simplicity is key – say things as if you were talking to someone. You don’t have to create intrigue.

Think about what brings the readers to the article in the first place. Do they need to learn more about your product? Are they looking for an easy and quick solution to a problem?

Your readers are going to keep reading because they need answers. Otherwise, they’ll have to call for support. So, make sure you deliver what they need, and no one will notice your intro.

Make your knowledge base easily searchable on the internet

The sooner you start talking about the topic, the better. If you need to explain a feature of your product, start your article with what that feature does. Simple as that!

One or two paragraphs are enough to enter into any topic. Just put three to five short sentences together, in which you explain what the article is covering.

Make sure your intro answers fundamental questions:

• What is the article about? — a function, feature, problem
• Who can act? — Premium users, all users, admins
• Where can the users access it? — what devices, what internet connection
• When will the feature be available? (if necessary)

When creating your  internal knowledge base , some articles may be short (less than 100 words). In this case, get right into the answer. It helps your customers save time and provides a better experience.  

Write step-by-step guides

Most articles in your knowledge base should provide an in-depth answer to “How?”, as they guide your customers through various processes.

Your instructions should be enough to provide your readers with all the details they need to get the most out of your product or fix their problem.

Highlight every step (with numbers, bold text, headings, or subheadings) to make them visible.

Don’t make assumptions. You’re an expert, but your audience has less knowledge on the topic. What seems obvious to you isn’t always self-evident for a new customer.

When you direct your users to a specific page or section, add a link to it. Some users feel more comfortable when you hold their hands a little.

When you furnish your articles with links and helpful details, you provide your customers with everything they need and they won’t have to call for support.

Avoid ambiguity, by being as precise as you can. Give examples to clear doubts , when you feel this could add value to your readers.

Follow the workflow

To write a knowledge base article, start with building a structure. It will help you put your ideas in order.

First, note down the main thoughts, then develop each one with the necessary details.

Organize your article logically – from the first step to the last one, in exact chronological order. And before writing the article, go through the process yourself. This way, you’ll make sure you don’t miss any actions or steps.

If any problem can occur while performing a step, make sure you mention it when you describe the stage. If your customer uses your instructions to get things started, this information will be useful.

When following a sequence isn’t necessary, start with the most simple notions and leave the complicated concepts for the second half of the article.

To make the article easy to follow, break the content into short paragraphs, organised into sections and subsections.

Use lists, bullets, and tables to express your ideas. The fewer words you use, the more comfortable the reading for your customers.

Illustrate your knowledge base article with relevant visuals

People are more likely to remember technical details with coloured images, which increase a reader’s attention by 82 percent .

Adding relevant images when you write a knowledge base article can help you explain notions better. Plus, they save you and your readers a headache.

Using screenshots allows you to show every step, instead of describing them in long paragraphs. Communication becomes faster, more comfortable, and efficient.  

Using a screenshot tool, you can capture the right image for every step of the process and back up every instruction with the perfect visual.

To provide clear instructions, you can also add graphic elements to your images, such as directional arrows or circles, to guide your reader’s attention towards the subject of interest.

Place the image after the text that contains the instruction. This approach allows the user to understand the information easier. Placing the image first can create confusion, if the reader doesn’t understand what’s illustrated in it.

Insert videos to improve the user experience

When people can choose between video and text to learn about a product, most of them go for the video.

This type of content can help to create a knowledge base article more engaging and more appealing to your customers.

To make useful videos, you need software for screen capture and editing. And to host your videos, you can use platforms like YouTube , Vimeo , or Loom .

Using videos can help you in optimizing your knowledge base SEO efforts . However, your knowledge base isn’t your business blog. So, use video content only when it allows you to add value to your readers.

Your brand is your identity. Carry your brand identity into your knowledge base

A video is a good fit for tutorials, tips, descriptions of your product’s latest features, and summaries of white papers, and other similar complex documentation.

To increase the usability of your knowledge base, you should backup your videos with text — an optimized transcript of the visual content added to the same page.

You can also use video to start your topic and continue with written instructions that are easier to follow. It can help users who want to apply in real time to what they read.

Google uses this approach to provide its users with more information about complex topics.

Videos are less useful when you’re guiding visitors to solve problems and errors. In these situations, your users are looking for quick solutions.

A well-organised text is easy to scan for answers, unlike video, which users need to watch from beginning to end to capture the information they need.

Place the video at the beginning of the article or at the top of a new section. If you post it in the middle of a text, you risk distracting your readers and losing their attention.

Create a table of contents for longer articles

There’s no optimal word count for a knowledge base article.  From less than 100 words to more than 1,500. The ideal size allows you to cover the topic area from all angles.

As a rule of thumb, the shorter, the better. Too many unnecessary words will make readers lose their patience. They’ll stop reading and call for support to get quick answers.

When the topic requires more words, break the text up to make the article easy to browse. Cut the material into small paragraphs using headings and subheadings.

To facilitate navigation, you could create a Table of Contents. This way, users who don’t need to go through the entire article can jump directly to the part they’re interested in.

MailChimp places a table of contents on the left side of the screen with the title “ In this article: “. As you read the article, the table highlights the section you’re currently on. If you want to go back or forth inside the text, you can do so by clicking the specific part in the table of contents.  

Include further reading suggestions

Your knowledge base software should be a network of excellent articles that complete each other. This way you give your users all the information they need to draw more benefits from using your product.

At the end of each article in your knowledge base, you can include a section for further reading, where you list articles on similar topics. You can name it using “ You May Also Like ” (Evernote), “ Related Links ” (Google), “ Related Articles ” (Facebook Help Centre), or other similar titles.

Providing additional information helps your readers find all the details they need without effort. Plus, you increase the time users spend on your site, which is a good sign for Google, and can help you improve your SEO.

Ask for feedback

An incredible self-service knowledge base article is updated on a regular basis. You need to keep every piece of content in your knowledge base relevant to your public.

The first step to improving articles is getting feedback from your users. So, at the bottom of each article in your knowledge base, ask your audience to evaluate the content.

Popular knowledge bases, like Google Support or Facebook Help Centre, use a straightforward system. They end their articles with a question like “ Was this information helpful? “.

Users can choose from two options – Yes and No. It’s quick, comfortable, and efficient.

When your article doesn’t get good ratings, it’s time to make some changes and improve usability.

10 more tips for crafting engaging knowledge base articles

• Keep a conversational tone. Write as you speak, to make sure your readers understand what you say.
• Don’t use advanced terminology. Your knowledge base should be accessible to all your customers, regardless of their educational background or area of expertise. Avoid slang and jargon, as well.
• Check your grammar. Errors and misspelt words draw attention and suggest poor quality content.
• Optimise for targeted keywords. This way, your articles will be easy to find with the Search function.
• Never add sales copy. People who access your knowledge base have already bought your product. Now they’re looking for help and extra information. Fail to give them that, and you’ll lose them instead of selling more.
• Link to other pages when you think another article can provide more details on a topic. This way, people who aren’t in the right place can easily find what they’re looking for.
• When covering significant problems, you can add a FAQs section at the bottom of the article. Here, you can give short answers to possible questions that a user may have after reading the text.
• If you can’t quit on all technical terminology, consider adding a glossary that users can refer to when they don’t understand a term.
• Keep a unique voice in all your articles. When you coordinate an entire team of technical writers, make sure they all respect the same guidelines.
• Use a single term for every concept across all your articles, to avoid confusion. This way, users who read more material to look for answers won’t end up wondering if you’re talking about the same issue.

Final thoughts

Writing an incredible knowledge base article takes effort. You need to express many technical details in easy-to-read content, to make it available for users with basic knowledge in your area of expertise.

By following these guidelines, you can manage to create valuable articles and provide your audience with consistent content, to help them help themselves.

To make your knowledge base article creation easier, you could use a knowledge base software like Document360 . Asides from improving the writing process through it’s simplified WYSIWYG markdown editor, it also makes it easier to improve your knowledge base’s information architecture.

Have you ever had trouble creating top-notch knowledge base articles? Did you use any of the above-mentioned practices? Let us know in the comments section below.

Are you ready to get started with your knowledge base? Why not give Document360 a try? With an uncompromised authoring experience, you’ll be writing incredible knowledge base articles in no time.

Christina Comben

May 17, 2018

Discover the latest tips & trends in creating knowledge base

By signing up, you agree to our Terms , Policy and GDPR

Share this Article

Related Articles

Thank you for subscribing.

You will be receiving an email from us shortly.

Trusted by successful businesses around the globe

The Whatfix Blog | Drive Digital Adoption

• Product Product Whatfix DAP Analyze, Build and Deliver experiences to application users and drive adoption with the Whatfix Digital Adoption Platform. Capabilities Personalization Omnichannel Adoption Automation Integrations Marketplace Analyze Behavioral Analytics Identify key user behaviours within an application Guidance Analytics Track usage of Widgets and Help content User Feedback Obtain user feedback on Help content in real time Build Content Creation Easily create and publish content in engaging formats Content Aggregation Make content from all enterprise systems accessible Content Management Seamlessly manage content in clearly defined stages Deliver Guidance & Training Offer step-by-step guidance and train users in real time Ondemand Support Offer contextual support at the moment of need In-app messaging Make announcements, conduct surveys and communicate change Core Web Desktop Mobile OEM Enterprise
• Solutions Solutions By Use Case Digital Transformation Adopt new technology without a dip in productivity Change Management Manage enterprise change with efficiency Remote Training Train remote team members with in-app learning User Adoption Increase user adoption of your enterprise software   Employee Onboarding Onboard new hires faster with in-app training Performance Support Improve employee productivity with self-service support User Onboarding Onboard new users faster with personalized walkthroughs By Platform Vendor Salesforce SAP Oracle Microsoft Workday By Application Category CRM HCM Insurance Source to Pay Meeting Solutions Digital Banking By Role Learning & Training Professionals Digital Transformation & Change Management Experts Product Managers Sales Professionals HR Professionals
• Resources Resources Resources Resource Library Explore intriguing customer success stories, videos, webinars and podcasts. Blog Learn more about driving digital adoption for your organization. Quick Links Customer Stories Webinars Podcasts Analyst Reports eBooks Whitepapers Videos Services Center of Excellence Whatfix University Support Whatfix Support FAQs
• Company Company Company About Us Careers Partners Events Newsroom Awards
• Back to Blog
• Knowledge Management

How to Write Helpful Knowledge Base Articles (+Examples)

• July 8, 2022

How easily and how quickly can a customer solve a problem they’re facing with your product or service? When a customer hits a dead end while using a product, the first thing they may interact with is your company’s knowledge base . 

With over 40% of consumers now preferring self-service over human contact , it’s become imperative for businesses to write in-depth, helpful knowledge base articles that empower customers with the documentation, guidance, and support to solve their own problems. 

We’ve compiled a comprehensive list of knowledge base best practices to make this process easy for you. But before we dive deeper into how to write a knowledge base article, let’s look at what it means and why it is an important tool for improving your customer experience.

What Is a Knowledge Base Article?

A knowledge base article is designed to be helpful documentation and tutorial content that can be found and use by customers to solve common questions and problems in a self-sufficent way. A knowledge base article features guides, videos, infographics, GIFs, and other visual aids that help your customers get the most out of your product or service.

A well-crafted knowledge base consists of dozens of articles that empower your customers with the knowledge and tools to resolve their issues without needing to contact customer service.

What’s the Purpose of a Knowledge Base Article?

A knowledge base article is a cost-effective way to help your customer find an answer to common questions in a helpful way, without the need to submit a support ticket or send an email. This ultimately helps you meet the gold standard for a high-quality, simple, and helpful customer experience. 

The main purposes of a knowledge base and its supporting articles include:

• Provide 24/7, on-demand customer support: Even if you have customers are on the other side of the world, a knowledge base article provides customer self-service support that will be there with them 24/7, whenever they need it. 
• Improve resolution rates: A well-written knowledge base article presents answers right at customers’ fingertips. It serves as an easy-to-use, self-serve portal that resolves issues very quickly.
• Reduce the number of support tickets: Knowledge bases and their support articles answer commonly asked customer support questions. Well-written knowledge base articles should answer many of your customers’ questions, which in turn will deflect many simple support tickets that burden your support team. This allows for your customer support team to focus on critical support issues and give more attention to your more valuable customers.  
• Acquire new customers: Knowledge base content appears in search results and helps boost SEO. In addition to helping and retaining existing customers, knowledge base articles help you acquire customers that are looking for similar products or services.

Having an effective knowledge base in place empowers your team to focus its time and energy on more pressing matters. In addition to the above use cases, a knowledge base helps you: 

• Present everything customers need to know in one place 
• Make your company look responsive and up-to-date
• Lower costs and achieve operational excellence
• Uncover insights to improve your knowledge base, product, or service
• Cater to different kinds of learners with videos, text, or annotated images

15 Best Knowledge Base Software in 2023

17 Best FAQ Page Examples & How to Create Your Own (2023)

15 Best Knowledge Base Examples in 2022

5 Components of a Helpful Knowledge Base Article

An effective knowledge base article is informative, engaging, easy to navigate, and unquestionably straightforward. Remember, the article is all about delivering valuable, easy-to-digest information to customers, prospects, and potentially even employees. 

Let’s look at some of the key components of a well-written knowledge base article.

1. Clear, simple writing

Use simplified language. It’s sometimes hard to explain a complex problem. But using simple, clear language to show complex thoughts is the best way to help your audience. 

Writing sentence with non-common and complex words is the last thing you want to do in a knowledge base article. Take the time to edit your article. Be aggressive in cutting unnecessary copy and material.

2. Visual content such as screenshots and graphics

Embedding graphics and screenshots in your knowledge base articles is a crucial step. Your customers will thank you for including graphics and screenshots as opposed to a page of black and white text. 

Using a mix of written copy and visuals to help guide users through your products and services provides more context, is more inclusive to different types of learners and provides overall more support. 

Usually, simple screenshots with annotations are perfectly fine – there is no need for heavily branded screenshots or over-the-top graphics. 

Here’s a simple example of how Apple helps its new customers learn to take screenshots:

3. Videos and GIFs

Adding video to your knowledge base articles is the perfect way to deliver faster, more contextual, and effective support content to your customers. Embedding videos help explain complex steps in less time. 

Let’s consider a complex process that many people have trouble executing, tying a tie.

If you’re reading a help article on how to tie a tie, an already tough-to-master process can seem even more complex. Instead, a quick 10-second GIF brings together the entire process into a short, more helpful explanation guide that adds more value than a long-form article.

4. Jump links and page navigation

Structuring your knowledge base articles is the difference between providing actual helpful support or coming off as confusing. 

Chances are that most of your customers are coming to your knowledge base stressed and annoyed. We recommend taking the time to keep your article as intuitive as possible. 

How do you do that?

Introduce jump links and page navigation elements into your knowledge base article. Here’s a quick run-through of how Whatfix segregates topics to help customers navigate through its knowledge base.

You can see that at Whatfix, we not only include left-side navigation that adds context to where the individual knowledge base article fits into the overall knowledge base – which provides related support content – but also a table of contents for the individual support articles you’re on.

This allows readers to quickly jump through the article and find the exact answer to a contextual issue they’re encountering.

You should also use headers, bulleted lists, shadow boxes, and other visual elements to provide structure, organization, and simple navigation to help draw your readers’ attention to the right spots of the article.

5. Simple article titles and tagging structure

Simple titles and tags help your customers find the right articles that have the answers they are looking for. 

Focus on writing simple and understandable titles. Look at what organic search your customers have made in the past and confer with your support team on some of the most asked questions to make this process easier. We highly recommend using action words like ‘how to’ and ‘using’ and leverage a keyword research tool such as Ahrefs to help with this process.

You should also tag each article with appropriate keywords to help organize your knowledge base content and make it more SEO-friendly. For example, tag all your knowledge base articles that cover account management topics – ie. updating billing, updating passwords, adding new seats – with a tag of “account management”.

8 Tips to Write Effective Knowledge Base Articles

Your knowledge base articles should make it easy as possible to find answers. It’s important that your knowledge base is formatted in a way that makes solutions clear and obvious. 

These eight tips will help you to write more effective knowledge base articles

1. Know your audience

Knowing your audience is the ultimate key to developing an effective knowledge base and writing knowledge base articles. 

Learning your audience’s technical understanding or preferred form of learning allows you to fully cater to their needs. As a rule of thumb, you should already have a solid understanding of your customer personas and their related behaviors. 

Ask your support team to create a list of customer questions they spend the most time on. Then, begin to write knowledge base articles based upon those common questions. This will help you provide a higher level of customer support, create a helpful knowledge base, and reduce the number of support tickets coming in.

2. Don’t make assumptions

Remember, most of your customers do not know the product as well as your internal stakeholders do. Put yourself in your customers’ shoes and rethink the assumptions you make while writing the article. 

For instance, do not use complex language, technical jargon, or internal lingo in your article. Assume that most of the customers are novice beginners. We recommend over-communicating even “simple” instructions.

3. Organize your content with headers and subheaders

This goes without saying but we’d be more than happy to lay it out for you. Organizing your knowledge base content is a critical step in ensuring customers find what they are looking for. 

For instance, including a table of content makes it easier for users to skip past the information they don’t need and navigate directly to the details they’re looking for.

Don’t forget to keep your headers and subheaders simple, as well as write and format them in an SEO-friendly way to help pull in long-tail keywords from Google and other search engines.

4. Use anchor links

As discussed earlier, include anchor links in your knowledge base articles. Anchor links are web page elements that allow users to jump to another location on the same page. It guides your customers to the desired information in a matter of seconds and significantly improves the user experience.

5. Create easy-to-read, skimmable articles

Imagine you are looking for a quick fix to your email scheduling issues within your new email marketing software’s knowledge base. You start looking for an answer to this issue, but become buried in text-heavy documentation that includes tons of information that is not contextual.

Knowledge base articles are usually quite long to begin with, but it’s essential to ensure that you don’t intimidate readers with a wall of text. Introduce bullets, tables, and a variety of formatting elements to ensure your articles are skimmable and easy to read.

6. Use multimedia such as video, images, and GIFs

A sure-fire way to improve the effectiveness of your knowledge base article is to include multimedia content such as videos, images, GIFs, infographics, and animations. No matter how ‘good’ your writing is, it will most likely be overlooked without visuals.

7. Write straightforward titles

As discussed earlier, writing straightforward titles helps you summarize what your article is actually about. Refrain from getting too creative with the title, instead write simple search-optimized titles. 

This will help direct readers to the answers they’re searching for – and will help your content appear in search results, providing more visibility for those searching for answers.

8. Create SEO-friendly articles

Try leveraging keyword research tools such Ahrefs and Semrush to keep your content SEO-friendly. These tools will give you insights into what your customers and users are searching for in relation to your support questions. It will also help you understand what types of queries are most commonly searched, helping you to plan new knowledge base articles.

Below you can see examples of potential knowledge base articles that Microsoft could write on MS Teams, based upon keyword research from Ahrefs:

Examples of Helpful Knowledge Base Articles

Here are a few examples of brands that have perfected the art of writing knowledge base articles to get you started:

1. HubSpot's knowledge base articles

HubSpot has an in-depth knowledge base that breaks down common support questions into helpful how-to articles. For example, let’s look at this knowledge base article on how to connect your domain to Hubspot .

Why is this knowledge base article example from HubSpot so helpful?

• It has a straightforward and SEO-friendly title – “Connect your domain to HubSpot”.
• It had a table of contents with jumplinks.
• It is well organized and structure well, with sections on “before you get started”, “connect your domain”,  and “related help content”.
• It includes step-by-step instructions with contextual screenshots.
• It asks readers if the content was helpful or not at the end of the article.

2. Apple's knowledge base articles

Apple is known for its incredible simple branding, user interface, and customer support. It’s knowledge base articles are no different. For this example, we’re look at Apple’s knowledge base article on how to set up your iPhone .

Why is this knowledge base article example from Apple so helpful?

• It has a straightforward and SEO-friendly title – “Set up your iPhone, iPad, or iPod touch”.
• It starts with jumplinks that takes users to different sections of the page depending on if they’re switching from another Apple device or if they’re switching from an Android device.
• It’s headers are organized in a straightforward way and are straight to the point.
• It uses custom graphics for each step of the process.

3. Microsoft's knowledge base articles

Microsoft has customers that span the globe and include various industries and business sizes. Many of its customers are enterprise-level, and contracts of that size require attention to detail and next-level customer support. For this example, we’ll examine Microsoft’s knowledge base article on how to download and install Office 365 .

Why is this knowledge base article example from Microsoft so helpful?

• It has a straightforward and SEO-friendly title – “Download and install or reinstall Microsoft 365 or Office 2021 on a PC or Mac”.
• It includes a simple navigation on the left of the page that includes related support content.
• It includes on-page pagination that navigates readers to the contextual help content, depending on if they’re Mac or PC users.
• It uses drop-down content menus that expand on support issues that may need for detail – this is fantastic, as it hides walls of intimidating text, but still presents readers with the opportunity to read more if they’re still confused with a topic.
• It uses shadow boxes, bulleted lists, and other types of on-page structure that organize and breaks up the content.
• It uses various screenshots throughout the article.
• It includes links to additional support content at the end of the article to the Microsoft user community and an email to its online support.

As customer expectations change, so does the need for your company to offer higher levels of customer support. 

With a digital adoption platform (DAP) such as Whatfix, customer-facing teams are empowered to create in-app support content that showcases how-to instructions, task lists, smart tips, and knowledge bases, all embedded directly inside their applications. This allows customers and users to learn by doing and provides on-demand support that empowers customers to find answers to their problems without leaving the application itself.

Whatfix also captures behavioral data, allowing organizations to identify the most commonly searched support queries to identify what new knowledge base articles should be written, as well as to understand what features are (and aren’t) being used.

See how Whatfix’s on-demand support is changing the way organizations onboarding, train, and provide support to their customers with in-app guidance for learning in the moment of need.

Request a demo to see how Whatfix empowers organizations to improve end-user adoption and provide on-demand customer support

Thank you for subscribing!

• Skip to main content
• Switch language
• Skip to search

Search Support

• Contributors
• Help articles

Writing guide for Knowledge Base articles

As a knowledge base contributor, you use words to help half a billion users. That's a big job. Users come to the knowledge base from all over the world, and they expect easy solutions, but we also want to delight them with our voice. How do you do that? Here are some things that we came up with in our research.

Table of Contents

• 2 Writing style
• 3.1 Write a good introduction
• 3.2 Organize the article effectively
• 3.3 Use descriptive heading titles
• 3.4 Make step-by-step instructions easy to follow
• 3.5 Readability
• 4.1.1 Fix the slug
• 4.2 Categories, products and topics
• 4.3 Keywords
• 4.4 Write a good search summary
• 4.5 Number of steps
• 4.6 Parallel structure
• 5 Style guide and copy rules

Write with the brand in mind. Mozilla is about user choice. We believe in freedom and flexibility. We value privacy and security. We are a community-driven non-profit with contributors all over the world who share common values.

You don't need to hammer this story in every time you write an article. It's just something to keep in mind when you're describing features.

Writing style

Write for a general, non-technical audience.

We want our articles to be usable by everyone, not just advanced users. This means we're writing for a general audience rather than one very familiar with computer techniques and terminology. Assume the person you're writing for doesn't know how to change preferences or add a toolbar button without step-by-step instructions. Also, we should assume that they haven't changed any of the default application or operating system settings.

To summarize, you should follow these guidelines:

• Keep it short. People come to the knowledge base looking for quick solutions. They might not care about the inner workings of the tool -- they just want to know what they should do to fix it. Go ahead and chop off some words. See how much you can convey with fewer words. It's like poetry!
• Keep it clear. Avoid jargon. Be specific. Use words in the title and in the article that the reader would use. If your 13-year-old nephew won't understand it, write it so that he would. See the next section for a more extensive guide.
• Be friendly, fun and empathetic. (In short: Be human). Okay, so users don't come to support expecting fun. That's what makes this powerful. Brighten up the user's day with a little humor. But be careful not to sacrifice clarity by using fun metaphors or expressions. If you're not sure how to balance this, just write straightforward instructions and use the tone in the introduction or conclusion.
• Beginning: this gives the reader some context. What is this article about and why should I care? Keep it short.
• Middle: The instructions go here. This should answer "How do I do this?"
• End: Are there any next steps to the article or feature? Tell the reader where he or she should go next if they want to learn more.

Read the next section for more comprehensive guidelines.

Writing style (comprehensive)

• Conversational writing style – Use an informal, active style similar to the way you'd speak to someone in person.
• Humor and emotion – Using humor is great but it's sometimes hard or impossible to localize. Emotions like surprise and "I didn't know that!" (not sure what to call that emotion) might be easier to include.
• Multiple learning styles – Just like in school, people learn differently. Also, everyone benefits from seeing the same content expressed in multiple ways.
• Repetition – When you explain something in a different way with different media, you're also, obviously, repeating it which is another good way to help people remember what's important.
• Images and video – Using images and video along with text is not only the next best thing to helping in person, it's an easy way of including multiple learning styles and repetition. Too many images, however, can make localizing an article more difficult, so try to add images only when it is helpful to a step or concept. For example, for a step that is clicking a button, you could say "Click OK " instead of adding a screenshot of that button's dialog box.
• Activities – Especially in a tutorial, it's good to give people something useful to accomplish. It's one thing to read instructions and understand the process, but it's often helpful to remind and enable people to try things out.

Write a good introduction

Along with the title and the table of contents, the introduction is what people will use to quickly determine if they are in the right place.

• For a tutorial or how-to article: Give a brief summary of what things can be learned.
• For a reference article: Give a brief explanation of the feature.
• For a troubleshooting article: Give a brief summary of the problem and its symptoms.

A good introduction can usually serve as a good search summary. Often you can just copy it into the "Search result summary" field and you're done.

Organize the article effectively

The general idea here is to try to build skills from simple to complex while trying to keep the information needed by most people near the top. So a simple, common solution would usually come before a complex or edge-case solution.

Use descriptive heading titles

Our articles are usually comprehensive so it's important to use descriptive headings to help people find the part of the article that they need. Take a look at your table of contents. Does it work with the introduction to give you a nice overview of the scope of the article?

Make step-by-step instructions easy to follow

The main thing to keep in mind when writing step-by-step instructions is to be careful to include all the actions needed to complete the task. If, for example, you have to click "OK" after selecting a preference in order to move to the next step, be sure to include clicking "OK" as part of that step. Some additional things to consider:

• There are always multiple ways to achieve a result. We should always pick the most user-friendly way by using the graphical user interface and menus when possible.
• Use full sentences when describing how to access the user interface.
• Include expected results when giving instructions (for example, Click "OK" and the window will close. ).

Readability

The text must be readable. To do this, you must:

• Split an article into small logical/semantic blocks with subheadings.
• Use numbered or bulleted lists.
• Write short or relatively short sentences.
• Avoid writing large paragraphs.

There is no limit to the amount of text. The more material, the better; however, you should not artificially expand it. Provide only useful, valuable, necessary information.

Technical guidelines

• To learn how to actually create a new article, see Create a new Knowledge Base article .
• See About the Knowledge Base for an overview of how the Knowlege Base works.
• See Improve the Knowledge Base for a full list of article documentation.
• Title length: Google's search results page will display up to 65 characters. Your title can be longer than this if necessary but make sure your important keywords are included in the first 65 characters.
• Capitalization: The first word in the title should be capitalized, as well as proper nouns and names, not every major word. Use "sentence" style, not "headline" style (the same applies to heading titles.) See the Style guide and copy rules section below for other rules on capitalization.
• Do not use a colon in the article title since it prevents creating a wiki link to that article ( bug 749835 ). Also make sure you don't have extra spaces in the article title, which will also prevent wiki links from working.
• Try to vary the way you name articles. Don't use the same words or phrases in every title. For example, don't always start articles with "How" and avoid using "-ing" task names such as "Setting the home page".
• Remember that the entire explanation doesn't have to go into the title. You can use the summary to give the user additional information about what is in the article.

Fix the slug

When you create a title, SUMO will automatically create a slug (the end of the URL for the article). The slug has a 50 character limit. Spaces are rendered as dashes. The slug should be consistent with the title, but given the tighter space restraint, doesn’t need to be the same. Be sure to check the end of the auto-generated slug. Sometimes a word gets cut off or it ends in a dash. Please fix things like that.

Categories, products and topics

For the most part, an article belongs in either the How-to or Troubleshooting category. Occasionally we write "How To Contribute" articles (like this one) or something in one of the other categories.

Articles are also "relevant to" at least one product. They also belong in one main "Topic" and, optionally, a "sub-topic".

The keywords field in an article can be used to improve search results on SUMO. It should be used only under specific circumstances though, as misuse can actually hurt search. We rarely need to use keywords. For details, see When and how to use keywords to improve an article's search ranking .

Write a good search summary

The article summary, along with the title, helps users judge whether an article will answer their question. We call this "User Confidence" and it directly impacts click through rates. Even if we serve the correct article at the top of the search results list, the user needs to make the mental connection between the search query and the results we display in order for them to click through to the article.

A summary for a how-to article should include the topics covered in the article. A troubleshooting article should try to include symptoms. In addition, a summary should follow these guidelines:

• Short and to the point. Remember classified ads? Write it like that. Search engines may cut off anything longer than 140 characters. If you use a longer summary, keep the important information at the beginning. Note: The KB software will show 20 characters remaining when the summary reaches 140 characters because the internal search limit is 160.
• Don't use wiki markup.
• We'll show you
• We'll explain
• This page explains
• This article describes

Number of steps

Use numbers or bullets to guide users through every step of the process. Whenever possible, try to limit the number of steps required to 6-7.

Parallel structure

Use the same phrasing or pattern of words for every step you write.

• Click on the Settings... button.
• Make sure that Form & Search History is not selected.

Style guide and copy rules

Like we said before, you should use an active, conversational style when you write. Avoid saying things like, "If a user's bookmarks have been lost" and instead say, "If you've lost your bookmarks". Here are other common style and copy issues you may run into when writing support articles:

Always use terms the way they appear in the Mozilla interface. For example:

• Plugins does not have a hyphen.
• Add-ons does have a hyphen.
• Home page is two words.

General computing terms:

• The Internet is uppercase.
• Website is one word. Web page is two words.
• Log in and log out are verbs. Example: "Log in to the website." The same applies to sign in and sign out. Do not use "log into" or "sign into".
• Login and logout are nouns (usually used as adjectives). Example: "Click the login button."
• Use email instead of e-mail.
• The plural of CD-ROM is CD-ROMs.

Links to mozilla.org should not contain the locale:

• Use https://www.mozilla.org/ instead of https://www.mozilla.org/en-US/

Capitalize the following items:

• Proper nouns and names, including brand names, product names and feature names
• The first word of a complete sentence
• The letters of abbreviations and acronyms unless they are normally lowercase
• The first word in numbered or bulleted lists
• The name of a key on the keyboard
• The first word of a complete sentence following a colon
• The first word in a heading or title

Don't use "i.e." and "e.g." . These Latin abbreviations can confuse people. For the sake of clarity, use "in other words" or "to put it differently" instead of i.e. when you want to explain something in a different way. Use "for instance", "for example" or "such as" instead of e.g. when you want to give examples.

Don't use serial commas in a list of items. For example, use "Extensions, themes and plugins" (without the serial comma), not "Extensions, themes, and plugins".

Use initialisms that are considered to be generally understood. For example:

Numbers appearing in the version of a product, error codes, keys and buttons will not be spelled out.

Write instructions in active voice. The present tense is easier to follow. Example:

"Restart Firefox to update" not "Firefox has to be restarted"

Spell out backslashes(\) and forward slashes(/) for paths and searches to avoid confusion.

Example: "Some pathnames to images contain backslashes (\\)".

Keyboard shortcuts Capitalize the first letter of a keyboard shortcut or combination of shortcuts. Ctrl + Shift + C

Don't use slang and idioms . All of our articles are translated into many different languages, so they are read and translated by non-native English speakers. Slang and idioms can be ambiguous which can confuse readers and make translation more difficult.

We have special visual styles for a number of items that can be achieved by adding the proper wiki markup around the item. See the Markup cheat sheet for the most common styles.

We have a special wiki markup – {for} – that allows you to target information for specific versions of Firefox or specific operating systems. For example, you display one set of instructions to people running Windows and another to people using Mac OS X (see How to use For for details).

Share this article: https://mzl.la/3BX1iW5

Was this article helpful?

These fine people helped write this article:

Grow and share your expertise with others. Answer questions and improve our knowledge base.

The Do’s and Don’ts of Writing Knowledge Base Articles

• Post on Twitter
• Share on Facebook
• Post on LinkedIn
• Post on Reddit
• copy-button#copy track#send" data-controller="track" data-track-category="ChatBot Blog" data-track-action="Share" data-track-label="Copy link" > Copy link to clipboard Link copied to clipboard https://www.knowledgebase.com/blog/knowledge-base-article/

If you work on a support team that uses a knowledge base, then creating, sharing, and updating help content is probably your bread and butter. A help article, in order to be effective, needs to tick a few boxes. After all, they are supposed to be a quick solution for customers in search of answers, and a time saver for your customer support team.

Read on for the do's and don'ts of creating knowledge base articles that deliver fast solutions.

What is a knowledge base?

A knowledge base is a collection of organized information and resources. The knowledge inside can range from product manuals, technical support articles, company policies, or FAQs, to onboarding materials, and help articles for customers.

In most cases, you can set up a knowledge base using a knowledge base software which allows easy storage, organization, and the maintenance of knowledge.

It’s particularly popular among online businesses with an online presence where three use cases dominate: 

• Providing customers with self service support 
• Improving the efficiency of a support team
• Organizing company knowledge

All in all, a knowledge base software can greatly improve customer experience. On one hand, customers get a better experience, because they can find answers in a help center that's open day and night, so they don't have to experience all the hiccups connected to chatting with an agent. On the other hand, agents can provide customers with comprehensive solutions much faster as all the information is ready-made and close at hand.

If you're looking for an easy way to organize and share your knowledge, try KnowledgeBase . You can use it to create a knowledge base, manage articles, and create both and external help center and internal knowledge base , making it easy for your customers and employees to find the information they need.

You can try it for free for 14 days.

What is a knowledge base article and what is it used for?

A knowledge base article is a written document about a specific, business-related topic. It can be connected to a product, a service, a company policy, frequently asked questions, and any other topic worth wider attention.

The purpose of an article is to provide an explanation. It should provide a reader with valuable information, solutions, or tips that fill a knowledge gap.

How to write a good knowledge base article?

Once you have your knowledge base up and running, it is time to fill it up with knowledge. Writing a good knowledge base article is not rocket science, but you need to remember about a few things.

Here are six tips for creating a great knowledge base article.

Know what to write about

Knowledge base articles only make sense only if someone reads them. Writing an article without researching the actual need for it is a waste of time, because it just won’t help anyone.

To avoid such a waste of time, effort, and money, you can delve into the analytics inside your knowledge base software. Most of them usually have a section with top views and top missed queries. There you go. Missed queries are one of the surefire ways to get an idea of a topic that will be of help to your customers.

Use a clear, concise writing style that is easy to understand

When writing knowledge base articles, it's important to keep a concise style that is easy to understand. This means avoiding industry jargon or overly technical language which might be unfamiliar to a reader. It can only result in an unhappy customer. 

It’s best to stick to the ELI5-like explanations. Establish a clear tone of voice and stick to it throughout your all articles. This will keep your knowledge base consistent. 

Make your article readable and scannable 

People on the internet don’t read anymore. They scan. 

This is something you should always keep in mind when writing any content. This requires writers to design their text in a way that is easy to read, or rather scan.

Break up your text with headings, images, videos, or lists. Including visuals can make the article more appealing and easy to scan, improving the overall customer experience.

Avoid lengthy paragraphs. Keep them short and simple. Four or five sentences in a paragraph is fine, but more than this and a reader sees a wall of text. 

Consider including:

• Sections with tips
• Colored boxes
• Bulleted or numbered lists

When it comes to sentence readability, it’s best to use simple language and short sentences, so a reader can quickly get the gist.

Such a reader-friendly article will help your customers solve their problems faster.

Add related reads

Help your readers get a better understanding of a topic by adding links to additional, extended reads. 

Don’t expect your reader to get acquainted with an entire subject in your article. They just need a quick solution. 

A good way out of this is to give your readers a choice and provide them with links to other relevant reads they might, or might not, find interesting. 

Make sure your article is up-to-date

One important tip for creating a great knowledge base article is to make sure it is always accurate and up-to-date. This not only helps to provide the most useful information to customers, but also reflects well on your brand and customer support team.

Regularly checking for new information related to the topic of the article will ensure that it remains accurate. You can set up a reminder to periodically review the article.

Create a clickable table of contents 

If you’re writing something lengthier, you can still make it readable for a reader. To do so, you should create a clickable table of contents. 

Readers can easily navigate through your text and quickly jump to the part that interests them the most. They don’t have to scan through an entire text to find what they need.

Creating such a table of contents actually also makes sense for shorter articles. It’s always easier to direct a reader to what they need. 

Proofread your work before publishing

Last but not least, it's always important to double check your work before publishing. Ideally, you should have someone else have a look at your text. Some smart and handsome.

This not only ensures your text is grammatically correct, but also helps to improve readability. Another pair of eyes might have additional suggestions for improvements, too.

A refined article reflects positively on your company and improves overall customer satisfaction.

Put knowledge to work

Knowledge base software for lightning-fast customer support and effortless self-service.

Trusted by 2,500+ companies

An example of a knowledge base article

Let's have a look at this help article from Buffer.

Right from the beginning, we get a title, we see the author, and the date of publication, or the last update. It gives us an impression that Buffer keeps their knowledge base up to date.

Then, there’s a short introduction that clearly explains what the article is about. 

Next, there’s a section for more advanced readers who might prefer editing with Canva and Pablo. Thanks to this section, we can jump to what we need without doing an additional search. 

After this section, we get a clickable table of contents which helps us navigate. It indicates what the article is about and lets us quickly move to the bit that interests us the most. 

The gist of this help article is a step-by-step guide to editing photos in Buffer. Each step is highlighted with a blue design, so it’s easy to follow. `The instructions are brief and supplemented with an image we can zoom in. All of this favors good readability.

The help article also contains notes that give broader explanations of particular functionalities, or a step. 

Buffer’s help articles are readable, informative, and well designed. Don’t hesitate to get inspired by their content. It’s a good example to follow.

How to promote your knowledge base articles?

Publishing your help article is half the battle. 

Now you should make sure that your article is visible and used.

Share it with your team

When it comes to promoting your internal knowledge base articles, make sure all necessary employees have access to the internal knowledge base. Consider reaching out to specific departments or teams that would benefit from an article and share it directly with them. 

Help your customers find what they need

When it comes to sharing your knowledge base articles with customers, there’s a few ways to do so.

Social media

If your business is active on social media, make sure you publish a post that will promote the new publication in your help center.

Email 

You can send out a newsletter to your customer base and let them know about a new knowledge base article. 

Homepage of your knowledge base 

Some knowledge bases have a separate “Recently added” section which is a great place to showcase newly released articles.

Are you looking for a knowledge base?

Providing a self-service option for your customers helps to reduce the number of support requests. Your team can focus on more important tasks and doesn’t have to bother with the same questions over and over again.

At the same time, a knowledge base with articles is faster than chatting with support agents. Your customers get instant answers and don’t have to worry about slow response times.

If you don’t already use a knowledge base as part of your customer support strategy, it’s good to consider it now. Check out our KnowledgeBase free trial and see how easy it is to build your knowledge base and write better knowledge base articles.

Share it with the world

• copy-button#copy track#send" data-controller="track" data-track-category="ChatBot Blog" data-track-action="Share" data-track-label="Copy link" > Copy link Link copied to clipboard https://www.knowledgebase.com/blog/knowledge-base-article/

Related articles

10 min read | Dec 06 | Tomasz Ziętek

10 Benefits of Knowledge Base Beyond Customer Service

A knowledge base is one of the most underrated tools not only in customer support but also... read more

14 min read | Sep 23 | Tomasz Ziętek

Building a Knowledge Base in 2023

If you already have the idea of building a knowledge base, you’re halfway there. In this... read more

9 min read | Jul 07 | Piotr Borkowicz and Tomasz Ziętek

[2023] 12 Best Knowledge Base Examples

Back in the day, when customer support teams had to rely on physical binders and folders... read more

Help your customers and support teams at the same time

Empower your support team with an internal knowledge base and a 24/7 customer self-service center.

Free 14-day trial No credit card required 24/7 support

Discover our other products

LiveChat Connect with customers

ChatBot Automate customer service with AI

HelpDesk Support customers with tickets