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:
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.