How to Write an Effective Knowledge Base Article

Sometimes the best support means getting out of your customer’s way.

A knowledge base can be a customer’s best friend during the “help me help myself” phase of exploring your product. But as Kathy Sierra shares in 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.

Help content before/after purchase

Docs can put the beauty back into documentation, but clean, organized writing doesn’t come in the same turn-key fashion; it’ll take sincere effort.

You need to be informative, engaging, unquestionably clear, and mindful of how and why a customer searched for help in the first place. Here are a few tips for doing exactly that.

In need of a knowledge base? Help Scout Docs is easy to use knowledge base software you can set up in minutes

Don’t make assumptions in your article

Customers check your docs to solve problems. Your most important goal is to be impossible to misunderstand.

While expertise operates on a spectrum, you should write as if the customer is a beginning user of your product. Skip the advanced terminologies and jargon, and be wary of mentioning to-dos in passing; customers are likely to hit roadblocks there. It’s safer to assume that they’ll need guidance for each step.

An 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?

  1. Before you continue, make sure to change your IP address.
  2. Before continuing, change your IP address by going to Settings > Manage Domain > IP Address.

The latter. Don’t self-sabotage by making assumptions about “simple” instructions. It’s better to over-communicate.

Make the content easy to browse

Don’t bog down or intimidate readers with a wall of text—when solutions aren’t easy to find, contacting support will be the customer’s next step. That’s a failure to communicate and a frustration for both of you.

Designer Rafal Tomal shows below how proper use of sub-headings and line breaks are a shortcut to an easily scannable doc.

Rafal Tomal - Content Styling

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

Below is an example from our Workflows article that showcases most of these elements in action:

Help Scout doc - Workflows

Tailor the experience around who you’re helping: a confused customer who is trying to pinpoint the section that solves his or her problem.

Make the content easy to read

For honing your voice in writing, one of the best resources on the web is Mailchimp’s Voice and Tone. A few suggestions I would add:

  • Plain prose is not too far from talk, but also not too near. Speak as you would to a friend but use editing to dress your thoughts well.
  • Consider your readers’ goals—is the article about learning the ins-and-outs of your product (curious), or fixing a bug or problem (frustration)? Adjust your tone accordingly.
  • For articles on non-troubleshooting issues, a bit of humor is fine, but the line of annoyance is quickly crossed.
  • Avoid slang and anything borderline. I once saw a writer get chewed out over the word “gypped,” which they used not understanding its derogatory nature.
  • Get to the point. Nothing drags down your doc more than spreading important information over too many words.

All writing must be engaging to keep people reading, but don’t let solutions become lost in flowery prose, excessive “personality,” and meandering jokes.


Your brand is special, so make sure every touch point with your customers is delightful.

Organize your article logically

Good documentation becomes great when it’s designed around the reader’s workflow.

Unless you want customers floundering about like a fish out of water assembling an IKEA TV stand, it pays to get the “flow” right. Here are three principles to live by:

1. Chronological order
As you might have guessed, it’s a must to organize a piece of help content in the chronological order of steps. The first thing customers should do must be Step 1.
2. Order by difficulty
If multiple tasks can be performed “first” (i.e., order doesn’t matter much), 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 win.
3. Be mindful of workflow

We all recognize that if you link someone to a video a few paragraphs into your doc, you increase the chances they’ll get distracted. Structure responses in a way that sustains activity and momentum. Avoid interrupting a problem-solving workflow until near the end.

Help Scout Reports article The styling above is great for “overview” articles.

Similar to constructing a great support email, place links strategically in sections to nudge customers into clicking them only when ready.

When introducing a longer article, create a quick table of contents at the beginning; it’s a small effort that genuinely enhances the experience. Even for articles of normal length, customers will appreciate being able to jump to the section they want.

Article Table of Contents

How about ending help content? Put yourself in the customer’s shoes and consider this monologue: “Okay, I’m ready to do this. Oh wait, what about…”

If you can think of any pertinent post-article FAQs, they could be added in the body content. You can also close the article with a quick list of common follow-up questions:

Docs-article follow-up questions

With smart structuring, you’ll have more users reading articles to the end, decreasing the likelihood that they’ll get frustrated, give up, and contact support instead.

Stick with simple article titles

Titles should be kept as straightforward as possible; restrain your creativity in favor of clarity. When stuck, what might a customer search for?

Remember that people search with caveman keywords: “how to migrate your WordPress website” turns into “migrate WordPress site.” Create titles that include the operative phrases.

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

Docs-article search titles

Vanilla, but obvious, just as it should be.

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,” etc.

Use images to save time and headaches

“Show, don’t tell” is the modus operandi of every knowledge base.

Say a Help Scout customer wants to learn about workflow templates. This is what they would see:

Docs-images and subheadings

Sub-headings and screenshots abound—why waste time with excessive text when I can just show you exactly what to do?

Here’s a handful of useful screenshot tools:

  • Ember — For Mac only, Ember has a Smart Drawing tool that detects circles, arrows, and rectangles and converts to shapes.
  • Skitch — From Evernote, Skitch allows you to annotate your images with simple sketches and shapes.
  • SnagIt — Affordable, and with plenty of features, SnagIt works for both Mac and PC and will allow you to quickly add visuals to clarify your images.

Add graphic elements like directional arrows to highlight important areas in crowded parts of the interface.

Article with annotations

Place these directly after a text instruction, assuming that users will look for what you’ve pointed out after reading.

If you say “Head over to My Settings,” follow with an image that highlights exactly where they should click.

How knowledge base content informs & improves

You’ll write documentation around the feedback you get, but many companies forget that the process is full-circle—what you write can come back around as a source of insight for your product and marketing.

In a smart article on the improvements he made to Sifter, Garret Dimon shared how his Docs reporting (screenshot below) turned into an additional channel for finding out where customers were getting stuck:

One of our secret weapons was the “Docs” report within Help Scout that lets us see what terms people are searching for within our help site. So, for example, if we see people are frequently searching for “How do I add a user?” then we know that we need to make it more obvious.

Sifter Docs report Sifter's Docs Report in Help Scout

Also remember that help content tends to serve as a first contact for prospects. If your article on Pricing is seeing a ton of hits, figure out why—is the pricing too confusing on the marketing site?

Follow the guidelines above and you’ll be well on your way to creating effective, coherent help content; a big benefit to both you and your customers.

Create a better experience for your customers with Help Scout.

Get Started
Download Your Free Guide

Download Your Free Guide

From your initial search to final purchase and setup, this (unbiased) resource will help make choosing any help desk easier.

Gregory Ciotti

Gregory Ciotti

Greg is a writer, marketing strategist and alum of Help Scout. Connect with him on Twitter and LinkedIn.