Knowledge Base: Creating a Knowledge Base Article

This article will help you successfully write and publish a useful Knowledge Base article (KB Article).  

Table of Contents

1.  Creating an Article
   
   • Template Outline
   • Keywords (Improving search results)
2. Submitting for publishing
   
   • Checklist for Creating & Reviewing Knowledge Base Article
3. Maintaining KB Article

1. Create an Article

1.  You have gathered information and are ready to create a KB article. 

Open the New KB article template

2. Select the appropriate Knowledge Base.  You will see only those Knowledge Bases you have rights to.

3. Select the appropriate Category. 

Select existing category or create new categories and sub-categories if appropriate

When creating KB articles, you may create categories and sub-categories for articles by:

• • Clicking the magnifying glass (next to category)
  • In the window that pops up, click near the bottom of the left most column.  This will provide a ‘+’ box. Click the ‘+’ box to create categories.
  • The same process can be used to create sub categories, only using the tier effect (moving over one column for each sub-category)

4. Enter an appropriate Short description (Title) 

5. Keep Valid to date to expire in 1 year unless the situation needs a shorter time frame.

6. In the Text box, type the content or paste it from another source.  

• If pasting content be sure to click Remove formatting when prompted.

7. Click Update in the top right.  This will save the article. It is not yet published.

Template outline

You can quickly copy the template source code to get you started from the article: KB Article Template Source Code. 

Template basics

In the Short description text box you will put your Title.  Do not put it in the Text field. Keep it simple and avoid jargon.  Ask yourself, what would a user search for?

1. Start with a problem
   
   1. At the top of the article, the first paragraph summarized the article. It tells the user what they can expect and do with the knowledge
      Example: Learn to format your knowledge base articles and use headings to break up content
2. Table of Contents for longer articles with multiple sections and steps
   
   1. shorter articles will not necessarily a table of contents with the information is direct and does not include multiple steps, screenshots, or require scrolling
3. User step-by-step instruction
   
   1. Use numbering
   2. Don't assume users are familiar with the topic
   3. It can be easy to miss documenting basic or obvious (to you) steps that must be taken
   4. Keep instructions simple: One step should cover one point
4. Use high-quality images that are appropriately sized to illustrate a task
   
   1. Do NOT capture an entire monitor or window
   2. Capture or crop to only the relevant area
   3. Use the screen capture image editing tools to circle or highlight relevant parts of the image
      Example:
      
5. Add related articles using the Related Articles section to encourage users to learn more about related topics

Keywords (Improving search results)

ServiceNow uses the title of the article first when searching.  It then uses the body of the article and last the keywords.  With it setup this way it is important to make sure your title is well thought out.  

Creating keywords

• Do not use words already in the title or body of the article
  
  • Depending on content you may not need keywords
• Do not use commas in between words; use spaces to separate words.

2. Submit for publishing

To submit for publishing follow these four steps:

1. Click Save.
2. Complete the checklist to review your draft.
3. Have the article reviewed by someone else.
4. When the article is ready, click Publish.

Once the article is Published, the article is available for individuals who have access to the knowledge base to search and view the article.

Checklist 

Process and Procedures

• Article is unique (no duplicate knowledge articles)
• Author has collaborated with knowledge owner and other stakeholders
• When knowledge exists elsewhere, provides context and link to external knowledge

Article Title

• Leads with the service or application followed by a colon (when applicable)
• Summarizes article contents

Content

• First paragraph is a problem statement or description that provides context
• Sentences are concise and easy to scan, paragraphs are short
• Content is well ordered; topics and subtopics are in a logical sequence
• Information is technically accurate, up-to-date, and complete

Format

• Topic and subtopic titles are formatted as headings
• Use numbers for steps, bullets for lists
• Link text, clearly references the target content 
• Links open in a new window except for in-page jump-to links
• Long articles have a table of contents that use in-page jump-to links

Images/Video

• Images are inserted (not attached)
• Images have effective alternative text
• Images are associated with the step they define
• When doing screen shots make sure to resize what you are going to screenshot to a smaller size so it is clearly seen without being extremely large.  Meaning if you have a larger monitor reduce the size of the window before doing a screen shot.  This will help keep image clear without being too large for document. See Best Practices Article

Keywords (Meta)

• Keywords include words not already in the title or content area that you expect someone to use when searching for content, including technical terms, jargon, and abbreviations

3.Maintain the KB article

Once the KB article is published it should be reviewed at least yearly to make sure it is still accurate and up to date.  Make sure to make any necessary changes as they are needed. If you leave USU IT, please reassign or ask someone to change ownership of any articles owned by you.

For further assistance, please contact your Department IT Support or the IT Service Desk