Writing a Knowledge Article

An email sent to the Service Desk team further explaining Knowledge Management principles and specifically covering how to write a good Knowledge Article.

The foundation of Knowledge Management is a well-organized, up-to-date, robust Knowledge Base. We currently use a OneNote document for this purpose, but we are preparing now to create our Knowledge Base in the ServiceNow tool. We should be using our time now to clean up our OneNote document and format the knowledge correctly so that it can be easily uploaded into the ServiceNow Knowledge Base and we can begin using it on Day One.

A Knowledge Article needs to be three things: Findable, Usable, and Accurate.


You need to be able to find an article when you need it. If the article exists, but cannot be found when searched for, then it is useless. Making an article findable is all about the search algorithms, usually based on the title of the article and the keywords. We also need to capture customer language – how they describe their issues – and make sure that is reflected in the article. Eventually, we want to have a customer-facing Self Help Knowledge Base and if they are using specific phrases or search terms that are not added to the article they will not find the article that will solve their issue. For example, we have a tool called Enterprise One. It is powered by JD Edwards and also says the word Oracle in big letters on the login screen. Some customers refer to this program as E1, Enterprise One, JD Edwards, or Oracle interchangeably. There might be a customer who searches the Knowledge Base for information on “JD Edwards”, but if all of our articles are written to reference Enterprise One (E1) they will never find the appropriate article.


A Knowledge Article needs to be usable. You need to be able to quickly read and understand the article while on the phone with the customer. Articles should not contain large blocks of text but should be broken down into bulleted or numbered steps with images, as needed, to clarify. Too many images just adds bulk to the article and makes it hard to read. Each image should have a purpose, clarifying one of the instructions that might not be well understood without the image. We should also format articles following our standardized Style Guide. This way a technician can glance through an article and pick out these words and know what to click on and what to type in, etc.


A knowledge article needs to be accurate. The information in the article needs to be correct. However, it is not useful to quarantine an article until the information has been verified. Instead, we verify the information in the article through its usage. Anytime you read an article you should edit it and correct or add information, or you should leave comments on the article with changes that they see need to be made. Then someone else who has more knowledge or access can incorporate those edit suggestions. It is not feasible for one Knowledge Manager, or even a Knowledge Team, to read every article that gets written and verify them before they are officially published. Each of us reads the articles as we need them to solve customer issues and we verify the information in the articles as we use them. Then, the articles that are used most often get extra attention from the Knowledge Manager to assure correct Findability, Usability, and Accuracy.

I have created a Style Guide for our Knowledge Base and saved it to our shared drive: \\hqdata\supportware\HelpDesk\Knowledge Management

Please read through this and be familiar with it. I am open to any suggestions or comments. I want this Style Guide to make sense for all of us and not just be a set of arbitrary rules.

In that shared folder there are also templates for basic Knowledge Article types: FAQ, How-To, and Known Error. When you write a new Knowledge Article (or are converting a OneNote page into a Knowledge Article) please open the correct template, then save it locally and rename it so you do not make changes to the template document. Edit each of the fields as needed, following the guidelines listed in each field. Then save the new Knowledge Article into the Draft Articles folder.

I will be reaching out to each of you asking you to take certain pages in our OneNote document and write them up as Knowledge Articles in this format and saving them to our Draft Articles folder in preparation for us uploading them into the ServiceNow Knowledge Base. The more we can do now the less we’ll have to scramble when the tool is implemented.

If you have any questions or suggestions about any of this Knowledge Article writing process please come see me.

Thank you for your work in this effort to capture and format our knowledge so that we can all more easily find and use it.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s