Skip to Content

Writing Effective Help Desk Knowledge Base Articles

Estimated Reading Time: 7 Minutes

Writing Effective Knowledge Base Articles

When technical issues are being resolved by support desk agents, it is rational to keep an account of the measures for every new challenge that surfaces. The problem may be due to software bugs, defective equipment, the necessity of more education to a user, or network configuration.

  • Support agents can learn from each other’s experiences with similar issues and avoid replication of effort.
  • Generation of reports for identifying trends and patterns that affect business goals by the analysts.
  • Accessibility of details to developers for providing a timely solution.

Besides documenting issues and responding to frequent queries of users, it relieves agents from addressing similar problems repeatedly.

A convenient way to make these records available is to keep them systematically within a knowledge base (KB). If made searchable by title, content, or keywords, knowledge bases such as PHPKB knowledge base management software are designed to aid agents as well as users in getting the answer they look for well in time. Most of the websites have a help section connected to a knowledge base. These knowledge bases can be internal, customer-facing, or both.

The Significance of Writing KB Articles Appropriately

Knowledge bases have two primary functions: information capturing and retrieval. Their efficacy depends on the accuracy and accessibility of content. Hence, it is pertinent to be focused on structure and process from the outset.

Knowledge Base articles must have the essential elements to make the KB optimally effective. If the response to a complicated issue (common among users, agents, and the company) is inappropriately framed, categorized, or tagged; it will never address the issue and will remain buried in the knowledge base as something of no use.

This article gives an overview and some best practice tips for writing effective help desk knowledgebase articles.

Prerequisite Before Publishing

Most commonly, agents create a new article when they are replying to a ticket by using the “Publish this question answer as an article in the knowledge base” option as highlighted in the screenshot below.

While creating a ticket-based article (by converting ticket reply as an article) in the knowledge base, sometimes agents overlook searching for the same in the knowledge base. So, before creating a new article in the knowledge base, the agent should first search the knowledge base by important keywords to see if there is any record of fixing the problem with the same title. If no matching results are found, only then a new article should be written. If there is already an article with that solution, then it should be updated, with a note, acknowledging the author of the original entry.

Elements of an Effective Knowledge Base Article

1. Title

The article title should contain particular keywords that uniquely identify the problem including application name, version, and relevant error message.

2. Procedure

There are four important aspects to each recognized issue and the way out which must be recorded for an efficacious base record.

  1. Problem: Description that delineates the issue, error messages, possible outcome, what it does cause before or after, potential temporary way-outs/alternatives.
  2. Steps: Important and decisive action that leads to a way out. It may be by removing the cause or unfolding clues to the specific problem area. This information, usually, proves to be of optimum value.
  3. Resolution: A detail of the way problem was solved which includes the way of identification along with proof that it was an authentic and lasting solution and just not a bug or an accidental fixture.
  4. Resources: These can be snapshots and links to knowledge base write-ups or other articles which aided in solving the problem.

Response to the questions that follow can be included in the steps to provide significant details to readers:

  • Was the problem escalated? If yes, at which level in the process?
  • Which experts were involved and what was their contribution?
  • Were there any software coding changes?
  • Was an update in third-party software necessary? What was the cost, and who approved it?
  • Was the purchase of hardware necessary? What was the cost, and who approved it?
  • Was it essential to change the network settings and configuration?
  • To what extent were the users discomforted by the issue while it was being addressed?
  • What was the gravity of the risk involved for business partners, vendors, stakeholders, different departments in a company due to the problem?
  • Any other significant comment, in-put, or observations that demand a follow-up?

3. Category Selection

An appropriate category should be selected for every KB article for the information to be located by browsing as well as searching. Categories are usually pre-fed in the knowledge base (under the categories management section) and chosen from an inbuilt list on the “Create Article” screen. PHPKB knowledge base software allows for the selection of more than one category for an article. This becomes highly effective where the information belongs to more than one category in the knowledge base.

4. Keywords (Tags)

The article content will contain important keywords that should be attached to an article. Think of keywords are search words. If you define a keyword and a user then searches using that keyword, this article is displayed. Use a comma to separate each keyword. Some external search engines may also use this for search engine optimization.

5. Publish Status and Version

An article (in-progress) can be saved conveniently as a draft, and maybe automatically saved by the knowledge base application. Once an article is completed, the agent submits the article to be reviewed by a quality checker (usually an editor or knowledge expert) before publishing it to the live knowledge base.

Best Practice Tips for Writing Effective Knowledge Base Articles

  1. Write for the right audience  — Articles should be created and analyzed from the perspective and problem area of the users who will be relying on them. They should be well-structured, precise, must provide clear steps, in a tone that comforts the users and transpire the way out. If the public will have access to an article, it will be a welcome call for the customer service department and marketing team to be part of the review process.
  2. Accurate Spellings — It is extremely essential that words are correctly spelled. Faltering here will cost customers unnecessary effort and botheration.
  3. Use Templates — Using custom article templates is one way of capturing and entering information in a consistently organized manner. Ideally, a knowledge base article template will include separate fields for Problem, Steps, Resolution, and Resources. This will make searching more efficacious.
  4. Use Appendices — If a problem requires a detailed explanation; shorten the steps and mention reference to an appendix at the bottom of the document where the details have been explained.
  5. Internal Linking — If some text refers to the process/steps explained in another article, it should be linked to that particular article using "Article Linking using Internal Link Markers" available in the PHPKB software.
  6. Review for Accuracy — Before publishing any article to the live knowledge base it should be analyzed for accuracy and completion. A diligent knowledge base manager handles all incoming articles to ensure consistency.
  7. Restrict Permission — Some users such as help desk agents (Level: Writer) can be restricted to publish knowledge documents until they are through with their training.
  8. Periodic Review — Set a review date for articles to be checked after a period of time. This is to prevent documents from unknowingly becoming outdated. If there are two similar entries better one should be flagged and a note should be included linking to a better record.
  9. Ask Experts to Contribute — A Knowledge base is an ultimate way to document the skill of a team’s optimum assets. Ensure that they consistently enrich the knowledge base with their experience and insight to get the maximum out of it. Provide some form of incentive to keep the knowledge base content up-to-date. Make it a team KPI and reward the most active contributors.
Writing Effective Help Desk Knowledge Base Articles