Table of Contents

How to Write a Knowledge Base Article Your Customers Will Love

How to Write a Knowledge Base Article Your Customers Will Love

A knowledge base article is supposed to be a self-service resource that helps your customers resolve issues independently. However, most knowledge base articles are difficult to understand, time consuming, or throw too much information at the reader, which defeats the purpose.

A good knowledge base article effectively answers a specific question for the reader. It’s concise, error-free, and uses visual elements to communicate with the reader in an engaging way. In this article, we'll walk you through six simple steps to creating knowledge base articles your customers will love.

Craft a concise title

A short and clear title is easy to understand. It tells customers exactly what to expect from your article from the get-go. For example, anyone would know what this help article is about at first glance at its title — the title is the question the user wants answered, so they immediately know this is the article for them.

Source: Portal 

Knowledge base articles aren’t stories; there’s no need to get overly creative with their titles. When crafting your title, aim to be clear rather than clever. State the specific question or pain point the reader has. When in doubt, ask yourself, "what question would a user ask to find this answer?"

Other tips to keep in mind are:

  • Add relevant keywords to your title so your article is easy to find. A keyword is a relevant term people are searching for. For example, Portal users could be searching for “integrate Portal with Wix.”
  • Make sure your title is short. Plos, an Open Access Research Organization, recommends that article titles be 12 words or less.

Create an article outline

An outline is created before writing the article, and it makes your article coherent. Coherence means that the main ideas and structure of your knowledge base article are presented logically, so readers can clearly understand the information you're trying to impart. It's easier to spot and correct idea gaps in an outline than to make changes in a completed article.

To create a good outline, make sure your ideas fit neatly together like the pieces of a jigsaw puzzle. There are three simple steps for this:

  1. List the main points you want to discuss in your knowledge base article.
  2. Add supporting details to explain each main point.
  3. Arrange the main and supporting points in a sequence so one naturally leads to the other. For example, if you’re writing a “How to write a knowledge base article your customers will love” piece, Step 1 should connect to Step 2 and so on — just like we’ve done.

Knowledge base article outline template

Title: How can I customize my portal?

Main Idea 1: Implement basic customization like adding logos and changing themes in your client portal.

Supporting idea 1: How to add your logo to Portal.

Supporting idea 2: How to choose a theme for your client portal.

Main idea 2: Portal has advanced customization options like extension modules and automation.

Supporting idea 1: How to add extension modules to your client portal.

Supporting idea 2: How to configure automation in your client portal.

Conclusion: Link to related help articles.

Flesh out the outline

Once you have a detailed outline, you can efficiently write your article. Here are three best practices for developing your outline.

Avoid assumptions and generalizations

Assumptions and generalizations may cause you to miss out on providing valuable information to customers, which defeats the purpose of an effective knowledge base article.

When writing a knowledge base article, your goal should be to answer the reader’s question comprehensively. Don't omit information because you think the user should know it.

For example, this article about how to create an invoice in Portal explains that customers can auto charge clients or ask them to pay manually. And it goes one step further to explain what both options mean — even though the difference might seem obvious — so customers can make a more informed decision.

Source: Portal

Use clear and plain language

Clear and plain language helps the reader to understand and use the information in your article easily. Let’s complete a simple exercise: Which of these statements leaves the least room for misinterpretation?

  • You can prorate your billing cycle
  • You can adjust your billing cycle for specific time periods, like your client’s start date

Clearly, the second statement. The first statement assumes that the client knows what “prorate” means, and the second one explains what “prorate” is.

Where possible, choose a simple word or phrase over a complex one. For example, say “start” instead of “commence” and “agree” instead of “concur.” Using simple words in your article doesn’t mean you’re ‘dumbing down’ the message. Rather, it allows you to communicate complex and important ideas to the reader as clearly and effectively as possible.

Avoid walls of text

Your customers are less likely to read articles with walls of text where sentences run into each other with few breaks.

There are several ways to break up walls of text so readers can skim through your article easily:

  • Add more paragraphs
  • Add media elements like images, videos, and gifs
  • Use formatting elements like bullet points, headings, and subheadings

Internal linking helps you avoid lumping too much information into a single article. Too much information can distract you and your readers from the specific issue being addressed.

Use anchor text to link to related content in your knowledge base article. Anchor text is a word or phrase that tells the reader what the linked page is about.

For example, in this article about billing modules, Portal provides a short answer to “How does a billing module work?” and includes links to other relevant information like “creating an invoice” and “creating a subscription.” These anchor links help Portal users easily find other relevant information related to their search.

Source: Portal

Add images, screenshots, and gifs

Visual elements like images, screenshots, and gifs help you communicate to the reader in fewer words. They also:  

  • Break up walls of text for better readability
  • Make your article more engaging
  • Improve content accessibility with alt text for people with visual impairments. Alt text describes visual elements to readers who cannot see them. Assistive technologies like screen readers pick up alt text and read these descriptions to visually impaired users

This doesn't mean you should use visual elements all over the place — you need to use them strategically to enhance your piece. Add screenshots to show customers how to complete different steps of a process you described in your knowledge base article. For example, Portal uses images in this article about messaging clients to show users how to create group conversations.

Source: Portal

Edit and proofread your article

Editing and proofreading make your article effective, clear, and error free. Editing tightens the ideas and structure of your article while proofreading checks for mechanical accuracy like grammar, spelling, and punctuation.

Before you publish your article, ask a professional editor and proofreader to review it. If you can’t hire one, use these self-editing tips to improve the quality of your article:

  1. Set the draft aside for a while.
  2. Use a writing assistant like Grammarly to scan the piece for common spelling and grammar errors.
  3. Delete unnecessary words like “that”.
  4. Eliminate repetitive words.

Knowledge base article template

Download our free knowledge base article templates. We’ve provided templates for different types of knowledge base content including How-to articles, Troubleshooting articles, FAQs, and Informational articles.

Publish your knowledge base article on Portal

Your knowledge base content needs a place to live so it’s easily accessible. You can create this central knowledge repository with Portal.

Portal is an all-in-one software for client collaboration. When you use Portal’s knowledge base software, you get:

  • Access to customer insights
  • An interactive content editor
  • A better client experience

Learn more about Portal’s knowledge base feature.