When help desk agents are troubleshooting technical issues, it makes sense to record the steps for every new fix that arises. Whether the problems are due to software bugs, faulty equipment, the need for more user education, or network configuration:

  • Agents can learn from each other’s hard work and avoid duplicating effort

  • Analysts can generate reports to identify trends and patterns that impact business goals

  • Developers can get the details they need when tasked to come up with a solution

In addition to documenting issues, providing written answers to common customer questions takes the load off of agents who find themselves repeatedly addressing the same issues.

An easy way to make these records readily available is to organize them as articles within a knowledge base (KB). Searchable by category, keyword and tag, knowledge bases like the ones included in Zendesk online help desk management software are designed to assist agents and customers in finding the answers they need fast. Most help sections on websites are connected to a knowledge base of some kind. They can be public and customer-facing, internal, or both.

The Importance of Writing KB Articles the Right Way

Knowledge bases are as much about retrieval as they are about capturing information. They are only as good as their contents are accurate and accessible. Therefore, they should be set up properly from the beginning, both in structure and in process.

Articles that are stored in a knowledge base must contain key elements to make the KB as effective as possible. If an important answer to a complex fix is buried because it isn’t properly written, categorized, and/or tagged, it is worthless to agents, customers, and the company itself.

This article provides an overview and best practice tips for writing help desk knowledge base articles.

Elements of a Help Desk Knowledge Base Article

When creating a ticket-based KB entry, the agent should first search the KB by keyword to see if they can find a record showing how the same problem was fixed. If there isn’t already a record in the KB, a new article should be created. If a similar article exists, the existing one should be updated by the agent, along with a note identifying the author of the original entry.

Topic

The topic, or title, should contain specific keywords that uniquely identify the issue including application name and version, error message, and relevant third-party software. For example, “FaceSpace User Profile Email Change Submit Button Invisible in Chrome Version 29.0.1547.62 m”, or “No XML File Found Error in Joomla 1.5 When Uploading Share & Follow 1.2”

Process

There are three essential aspects to each identified problem and solution that must be captured for an effective knowledge base record.

  1. Problem -- Details that identify and describe the symptoms of a unique issue including specific error messages, possible triggers, what happened or didn’t happen after, and potential temporary workarounds / ways to avoid it

  2. Steps -- Key decisions that were made while troubleshooting that resulted in progress towards a solution, whether by eliminating possible causes or revealing clues to the true problem area. This information often proves to be the most valuable

  3. Resolution -- A description of the resolution itself, including how it was recognized, and evidence that it was a true fix and not just a glitch or coincidence

  4. Resources -- Screenshots and links to knowledge base articles or other references that were helpful resources while troubleshooting

Answers to the following questions can be included in the steps to provide important details to readers:

    • Was the issue escalated? If so, at what point in the process?

    • Which expert staff were involved, if any, and what did they contribute?

    • Were software coding changes made?

    • Was an update to third-party software required? What was the cost, and who approved it?

    • Was the purchase of hardware necessary? What was the cost, and who approved it?

    • Was it necessary to change network settings or configuration?

    • To what degree were users inconvenienced by the problem while it was being resolved?

    • What level of risk may arise for business partners, vendors, different departments in the organization, or other stakeholders due to the impact of the issue?

Any important notes, comments or observations that need follow up?

Tags

The answers to the above questions will contain important tags that should be attached to an article, and may be added automatically based on business rules and workflow. Tags are searchable keywords that help organize content for internal purposes. For example, an article may be tagged with: agent_klanders; problem_software_bug; escalated_Tier2; resolution_codechange; developerassigned_approved_JB; notify_hostprovider; customer_new; customer_hot. Articles should always be tagged with the names of each contributor.

Section and/or Category

An appropriate category (in Zendesk they’re called Sections, and sub-categories are called Categories) should be chosen for each KB article to allow the information to be found by browsing as well as searching. Sections and categories are usually pre-established, and chosen from drop down lists.

Publication Status and Version

An article can be saved at any time as a draft, and may be automatically saved by the KB application so that older versions can be resurrected easily.

Once an article is finished, the agent typically changes the Publication Status to Ready for Review or simply submits the article so that a quality checker can review it before adding it to the live knowledge base.

Best Practice Tips for Writing Effective Help Desk Knowledge Base Articles

Write for the right audience -- Articles should be written and reviewed from the perspective of the people who will most likely be relying on them. They should be well organized, short but sweet, and provide clear, numbered steps written in a user-friendly tone. If the public is going to have access to an article, marketing and customer service departments will likely wish to be part of the review process.

Be sure to check spelling -- Especially when it comes to keywords and tags, it’s important that words are spelled correctly. If not, someone searching under the printer error “PC Load Letter” might not find the perfect solution because it was spelled “PC Lode Leter”.

Use templates -- Custom templates can be created to make sure information is captured and entered in a consistent and organized way. Ideally, a knowledge base template will include separate fields for Problem, Steps, Resolution, and Resources to make searching more effective.

Keep things simple with appendices -- If an issue requires a lot of detailed explanation, keep the steps short and refer to an appendix at the bottom of the document where the majority of the details are explained.

Quality checks -- Before any article is added to the live database, a quality checker should review all submitted articles for accuracy and completeness. Ideally, a dedicated knowledge base manager handles all incoming articles to ensure consistency.

Control at the source -- Permissions can be used to restrict some users, such as new help desk agents, from submitting articles until they’ve completed training.

Establish a reference system -- All articles should be assigned a unique identifier for quick reference. Abbreviations can be used for sections and categories, and numbers used for individual documents. For example, NC2312.2 could be used for Network section, Configuration category, 2312 for the article’s number, and .2 to indicate it has been revised twice.

Use tags for flagging -- Tags are an easy way to identify KB entries that are miscategorized, mistagged, similar to another entry, or need review for clarity or updating. For example, articles that need to be checked for accuracy can be tagged with “review_accuracy”, while duplicate records can be tagged with “review_duplicate”. If two similar entries are found, and one is better than the other, the less effective one should be flagged, and a note included linking to the better record.

Ask experts to contribute -- Knowledge bases are the best way to document the expertise of a team’s best assets. Be sure they are regularly adding their experience and insight into the KB to get the most out of it.