How to write an effective knowledge base article

How to write an effective knowledge base article

Effective knowledge base articles can save an organization millions of dollars and hours of wasted time. As an IT leader, you want your employees to get the help they need without having to file a ticket and wait hours and days. This is the goal of every knowledge base article.

A good knowledge article can help employees and agents alike — because self-service increases the productivity of the entire organization. We've helped hundreds of companies perfect their knowledge base, and now we're ready to share what we've learned.

There are three parts that come into play when writing a knowledge article:

  1. Identifying the right structure
  2. Differentiating between different types of articles
  3. Enabling your employees to self-service

Structure of a knowledge base article

The best knowledge base articles are easy to understand. So, we recommend establishing a clear writing style within your organization and enabling every person who writes knowledge base articles to use it.

The best articles:

  • Use simple language. They don't rely on jargon.
  • Are organized in an intuitive way.
  • Focus on a single topic.

Effective headlines

The best headlines are simple and clear. Don't write titles that only focus on a problem's symptom — as they may vary across employees.

When writing headlines, mention the main subject prominently. If your organization uses two different communications platforms, include the name in your title. For example, "setting up Zoom video conferencing" is a clear title that lets the employees know exactly how they'll be helped.

Add contextual information only if it helps differentiate the article. For example: "setting up printers in the Austin office" vs "setting up printers in the Toronto office". Establish and use the same contextual information across all knowledge base articles.

Writing the content

Establish the context of each article immediately. For example, an article applying only to Mac OS users should state that upfront, preferably in the title. Don't rely on organizational hierarchies — tell the reader exactly how the article is relevant to them in the title and body of the article.

The best way to write an effective knowledge base article is to talk like your end-users. Try to use the terminology your employees use — including adding keywords that describe symptoms. For example, users may say "my laptop screen turned blue" — and if the resulting article doesn't list that symptom, they could assume the article won't resolve their issue.

To ensure you're using up-to-date terminology, check out these resources:

Don't add hyperlinks unless:

  • You can't fit all the information into a single article or
  • You need to point to information that most readers won't need, but a few might.

If you do need to add hyperlinks, keep the anchor text as small as possible while clearly spelling out what the target of the link is.

How to write different types of knowledge base articles

There are four types of knowledge base articles. Each should be written with the specific goal of enabling self-service.

Task-based articles

Task-based articles provide general overviews of a process and use specific steps to guide employees toward a solution. Most of your knowledge base articles should be of this type.

To make it easier for users to find task-based articles, the title should follow the phrase "I want to know about...". For example, "How to connect to the VPN".

Intro articles

Intro articles will give employees beginner context about a system in your organization.

To convey that the article provides background information (rather than a how-to procedure), start the title with "about..." or "what is...".

FAQ and user guide-style article

Setting up a FAQ is an easy way to address common questions from employees, but to enable self-service, keep your answers short. If a question requires a lot of context or a task procedure is useful, it should have its own article.

Policy articles

These articles explain organizational-level policies or procedures. Choose a title that makes that clear. For example, good titles might start with "What's our policy for..." or "Can I..."

Enabling your employees to self-service

To truly enable self-service and see an impact on your help desk, you need to meet employees where they are — in enterprise chat platforms. Today, however, employees often revert to DMing their preferred IT agent or asking their questions within an existing IT channel.

You need to create a single interface for all knowledge — bypassing the frustration an employee feels when they don't know how to get the answers they need. At Consumers Energy, for example, employees are able to engage directly on their enterprise chat platform. They can ask any question from HR to IT and get an answer in minutes.

By following this checklist, you can effectively create a knowledge base article that enables self-service for your employees.

Knowledge-Base-Articles-TOFU-Guide-Checklist-Animation-600x628