8 Best Practices for Writing Effective Knowledge Base Articles

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

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

The best help content is informative, engaging, unquestionably clear, 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 impossible to misunderstand.

Write your help desk articles imagining that the people reading them are complete beginners. Skip the advanced terminologies and jargon, 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?

  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.

Option one assumes that the reader knows how to change their IP address. Option two, on the other hand, caters to 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 key details out of your documentation.

2. Use anchor links in lengthy articles

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

When you need to write a lengthy knowledge base article, it helps to 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.

Anchor Links Example

Even for articles of normal length, customers will appreciate being able to jump to the section they want.

3. Make the content easy to skim

Another tip for lengthier knowledge base articles: 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.

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

Rafal Tomal - Content Styling

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

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

Help Scout doc - Workflows

It uses a variety of different 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 key pieces of information on the page.

4. 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 how you talk, but it’s also not too near. Write as you would speak 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.

5. 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 trying to assemble 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 one.
  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 quick win.
  3. Be mindful of workflow: Structure responses in a way that sustains activity and momentum. Avoid interrupting a problem-solving workflow until near the end.

To avoid interrupting the reader’s workflow but also make sure you’re addressing related questions and issues, you can close the article with a quick list of common follow-up questions.

Docs-article follow-up questions

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

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.

Article Table of Contents

And while linking to other helpful articles is definitely 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. You want to make sure nudge customers to click links only when clicking a link is the natural next step.

7. Stick with simple article titles

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

Remember that people search with basic 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

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 the modus operandi of every knowledge base.

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 and/or GIFs showing each step in your interface.

Say a Help Scout customer wants to learn more about assigning conversations. This is what they would see:

Screenshots Example

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

Snagit is a simple, affordable, and feature-rich screenshotting tool and editor that works on both Mac and PC.

In addition to making it easy to capture screenshots, you can also use SnagIt to add numbers and arrows to your screenshots and blur sections of text that contain sensitive information.

Article with annotations

For GIFs, GIPHY Capture is a great free tool for Mac that makes it easy to capture a sequence of steps on your screen.

Using your knowledge base data to improve your product

Writing effective knowledge base articles is the first step in providing better self-servicing options for your customer, 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 sometimes serves as a first point of contact for prospects. If your article on Pricing is seeing a ton of hits, investigate why that’s the case. Is the pricing too confusing on the marketing site?

So in addition to following the best practices above to create effective, coherent help content, make sure you’re also reviewing your reports regularly to get ideas for how your knowledge base content, marketing, and even your overall product can be improved.

Gregory Ciotti
Gregory Ciotti

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

Get started with Help Scout

A better experience for your customers, fewer headaches for your team. You'll be set up in minutes.

Free 15-day Trial