Effective service desk operations runs on knowledge management – specifically, knowledge base (KB) articles. Knowledge Base articles can help your end users solve problems on their own and help your IT Support team resolve issues more efficiently. KB articles also serve as a training tool, encapsulating your knowledge, procedures, and processes in an easy-to-digest, topical format.

But what happens when knowledge base articles are less than useful? As often happens, knowledge is documented as a rushed, last resort, either by marketing team members who don’t understand technical language or by engineers who can’t easily “dumb it down” for the average user. As a result, organizations have knowledge base articles that are topically correct but practically unusable.

In this article, we outline 7 tips for improving the quality of your ITIL knowledge base articles so they are user-friendly and effective. This is based on our 20 years of experience helping at all levels of support.

Tip 1: Write for the Audience

The first tip is to write for the audience. In a knowledge base, there are four common audiences for KB articles:

  • The end user looking to troubleshoot their incident or place a request
  • The Level 1/Level 2 IT support person looking to walk an end user through the steps to resolve the incident or respond to the request
  • The Level 3/Level 4 Engineer or Technician who needs to perform highly technical solutions
  • The customer looking to answer questions, which may or may not be technical in nature

Writing for the End User

When writing for an end user, you’ll want to write with lots of simple language and use of “you” POV. For example:

“If refreshing the page does not work to clear the error message, the next step is to clear your cache and cookies. Here’s how to do that…”

Solutions given in the article should be within the user’s control. Options to escalate to a service desk ticket should always be given if the user gets stuck.

Writing for the Level 1/Level 2 IT Support Person

The second possible audience for knowledge base articles is the Level 1 or Level 2 IT Support Person.

Writing for the Level 3/Level 4 Technician

The third possible audience is the escalation technician at the Tier 3 or Tier 4 level. This person could be a NOC engineer, a developer, a DBA, or some other technical role. At this level, the technician needs

Writing for the Customer

Sometimes, technical knowledge base articles for the end user and marketing and sales knowledge base articles are intertwined. In this case, the person in charge of knowledge management may need to write articles for both types. When writing for the customer, remember that they are likely looking for answers to specific questions and want easy-to-follow information.

Tip 2: Go Step-by-Step (Even the “Duh” Steps)

The second tip is simple, at least in theory: organize your knowledge base content step-by-step, in a way that makes sense for your end user. If your end user is barely technical, the technical support content they get should be very simple. Do not assume that anything is known, so start at the beginning and follow each step the end user takes.

Include steps like:

  • Navigating to a part of the page (upper right, lower left, etc)
  • Clicking on a specific button or area
  • Typing text into a prompt
  • Clicking a final “submit” or other choice
  • Testing the success of the steps they took

Tip 3: Use Imagery and Video to Augment Text

The third tip is to rely on more than one learning style to present information. So each article should, ideally, contain:

  • Clear, easy-to-understand text appropriate to the audience
  • Images which explain the steps
  • A video walkthrough, especially for Level 1 knowledge meant to be consumed prior to escalation to the service desk
  • Generated captions, if possible, for any video created

There are a few reasons for the multiple modalities. The first is understanding; when you use multiple learning styles, you give everyone the best chance at understanding your content. The second is accessibility; not every end user can access video-only content, and having text that can be read using screen adjustment devices or screen readers will help.

Tip 4: Use Keyword-Appropriate Titles and Categories

The third tip is to create your KB articles using keyword-rich, question-focused titles. Instead of “Email Help”, you could write, “How to Troubleshoot Common Outlook Issues”. Instead of, “VPN KB”, you could write, “How to Connect to the VPN”.

And then, these keyword-rich articles should be sorted into categories that make sense. Either this can be ITIL-sorted (for internal IT support teams) or function-sorted (for end users).

Example of ITIL-Sorted Categories:

  • Access
  • Infrastructure
  • Hardware
  • Software

Example of Function-Sorted Categories:

  • Login Issues
  • Billing Issues
  • Technical Support
  • Sales Questions

Tip 5: Edit for Active Voice and Clear Words

The third tip for writing better KB articles is simple: write in active voice instead of passive voice.

Instead of writing, “When the button gets clicked, it will take you to the form to fill out your information.”

You could instead make it active by writing, “Click on the red button that says “More Information”. After you click, you will be redirected to a form to fill out.”

Active Voice writing puts the subject first, followed by the action and object. In these sentences, the person becomes the subject of the sentence. It’s also facilitated by clear, powerful verbs. So instead of writing “do it”, you could write “click the button”. Remove any instances of get, do, it, and thing and instead replace those generic words with clear verbs and nouns. That way there is no confusion about the action you want someone to take.

Tip 6: Allow Article Rating

A sixth tip is more for knowledge managers to worry about, and it’s this: allow for article rating, especially for end user facing articles. Like any other customer, knowledge base end users will let you know when content doesn’t solve their problems. Low rated articles should be reviewed as often as possible, or at least once per year.

Tip 7: QA Against a Problem User

Finally, the last tip is to QA your KB articles with a “problem user”. By problem user, I meant one or two end users in your organization who put in a lot of tickets or feel easily confused or overwhelmed with technical steps. Users like this will help you spot missing or unclear steps in your article that got missed in your internal review.

Yes, Aptude Can Do That.

For over 20 years, Aptude has helped companies better manage their IT Support, ITSM, and legacy application support. ITIL-based support teams can ramp up in a myriad of models in as little as 2-3 weeks and will touch base as often as you need to discuss metrics and review feedback in an iterative process.

Get Tier 1 through Tier 4 IT Service Desk Agents who can help with…

ITIL® IT Support, including incidents and requests processing for a variety of applications

IT and Non-IT related Service Desk Initiatives Support via multiple languages including: English, Spanish, or Portuguese

Production Support and Application Maintenance – corrective maintenance, bug fixes, production support, and coordination among Levels (internally or externally)

Production Enhancements – adding new functionality such as integrations, interfaces, applications, and reports

Click here to book a no-obligation call with Guy DeRosa

*ITIL® is a registered trade mark of AXELOS Limited.