Tips & Templates for Writing Great Knowledge Base Articles - 6 minutes read


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.

For more  Fubo.tv/firetv

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.

For more information  Peacocktv.com/tv

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.

For more My5.tv/activate

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.

For more  www.microsoft.com/link

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.

FOr more  Vudu.com/start

5. Organize your knowledge base article logically

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

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

  1. Chronological order: It’s a must to organize a piece of help content in the chronological order of steps. The first thing your customers should see is the first step in the process they need to take to succeed.
  2. Order by difficulty: If multiple tasks can be performed “first” (i.e., the order doesn’t matter), have customers do what’s easiest first. Early friction decreases the likelihood that they’ll finish or even follow your advice, so begin with a quick win.
  3. Be mindful of workflow: Structure responses in a way that sustains activity and momentum. Avoid interrupting a problem-solving workflow until near the end.

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

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

For more  Spotify.com/pair

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.