How do I Write and Submit Knowledge Base Articles?

Question:

How do I write and submit knowledge base articles?

What is the knowledge base style guide?

 

Answer:

All technicians have the ability to submit a knowledge base article.

* Please Note: all articles will be reviewed before they are published.

 

Writing an Article:

  1. Go to the Knowledge Base page.
     
  2. Select New Article.

New Article Button on right side of screen.

 

  1. Review the knowledge base style guide here. All knowledge base articles must reflect this standard format.
     
  2. For the "Subject," please create a simplified question for your new article starting with "How do I..." Please capitalize the first and last word, in addition to nouns, pronouns, verbs, adjectives, and adverbs.  Please do not capitalize articles, prepositions, or coordinating conjunctions. 
    Example: "How do I Submit a Ticket for Someone Else through the Service Catalog?”
     
  3. Click the "Templates" Button

screen shot of article editing bar with Template button circled.

 

  1. Select "New Knowledge Base Article - Customer Facing".  This will bring an example article that contains much of the style guidelines.  

screen shot of list of KB article templates

 

  1. Update the placeholder content with your desired content.
     
  2. Click "Save" often when working on the article.
     
  3. Select "Settings," located above "Subject," to insert Tags (keywords) for the article.
     
  4. When you are finished, click "Save."

 

Knowledge Base (KB) Style Guide

Table of Contents:
 

  1. Standards
     
  2. Subject
     
  3. Question
     
  4. Answer

 

Knowledge Base Standards:

  1. A knowledge base article is broken down into three main sections: (1) the subject, (2) the question, and (3) the answer.

screen shot pointing to subject, question and answer areas

 

  1. The body of the article should be in the "Normal" style.  Font in Normal is Helvetica, size for the body is 14pt.
     
  2. All KB articles should be "tagged" appropriately.
     
  3.  The words “knowledge base” and “service catalog” should be lower case unless they are in the title of an article.
    Example: All faculty, staff and students can browse the knowledge base.
    Example Title: How do I use the Knowledge Base to find “self-help” solutions?
     
  4. "Sage Service Request System" is always upper case.
     
  5. Any time "TeamDynamix" needs to be referenced in an article, please call it the ITS Request System instead of "TeamDynamix." 
     
  6. All images used in a KB article must have alternative text, this is to ensure we are compliant with ADA standards.
    The primary purpose of alternative text is to describe images to visitors who are unable to see them. Alternative text is read by screen readers, and the text is displayed for browsers that block images. Including alternative text with your images ensures all users, regardless of visual ability, can appreciate the content on your site. So, please be mindful of how you describe your images in the alternative text.
     
  7. The article footer will hyperlink the phrase "submit a service request" to https://branded.teamdynamix.com/TDClient/1951/Portal/Requests/TicketRequests/NewForm?ID=40285 and open in a new window / tab.

 

Knowledge Base Subject:

  1. Start with “How do I,” if possible.
     
  2. Should be in the form of a simplified question.
     
  3. Capitalize the first and last word, in addition to nouns, pronouns, verbs, adjectives, and adverbs.  Please do not capitalize articles, prepositions, or coordinating conjunctions.Example: "How do I Submit a Ticket for Someone Else through the Service Catalog?”

 

Knowledge Base Question:
 

  1. Use this opportunity to expand, if possible, on the question used for the "subject." Consider elaborating and providing additional detail to the "subject" question.  Reminder: The subject is a simplified and concise version of a question.
     
  2. Should be in lowercase except for first letter in the sentence and proper nouns.
     
  3. If you have a KB article that answers multiple related questions with minimal steps, break the question into those various questions then anchor those questions to their related steps (this article is an example).  Multiple questions should use bullet points.

 

Knowledge Base Answer:

  1. The first line should always be in italics and state who has the ability to perform the KB Article steps.
    Examples:
    All faculty, staff and students have the ability to…
    Faculty and staff have the ability to…
    Students have the ability to…
    Only faculty have the ability to…
    Only ITS Staff has the ability to…
    Only HR Staff has the ability to…
    ​​​​​​​
  2. Each step should be numbered 
     
  3. Steps in KB articles should be grammatically correct and end with the proper punctuation mark.
     
  4. Steps in KB articles should be concise (as short as possible) and “to the point,” with one or two actions per step and a maximum of two lines. They should not be paragraphs.
     
  5. There should be an extra break / space between each step and a screenshot so that the article is easier to read.
    To add a space: At the end of each step hold shift while pressing enter to insert a “line break.”
     
  6. Proper nouns in steps should use quotes for emphasis and punctuation marks remain inside the quotes.  ​​​​​​​
    Example: Please select "File," and then select "Save."
     
  7. When using single-line text examples, please enter a line break at the end of the step, then type "​​​​​​​Example:" in bold (see above step for example).
     
  8. When using multi-line text examples, please enter a line break at the end of the step, then type "Examples:" in bold and add another line break after "Examples:" (see step 1 in "Knowledge Base Answer" for example).
     
  9. Screen shots:
  • ​​​​​​​Use 1 pt red strokes for indicators, such as arrows and circles, when creating screen shots. Please do not use hand-drawn or highlighted areas.
  • Screen shots must be outlined with a 1 pt black border when inserting screen shots into answers. ​​​​​​​
  • Reminder: Please fill out "Alternative Text.
  1. Example of image properties screen highlighting alt text and border

 

  1. If the answer responds to multiple questions:
  • Each question should be stated before the steps in a bolded Heading 3 using a line break before and after the heading.  
  • Please separate each response after the first with a Horizontal Line Break.
  • There should not be a line break between the last step (in an answered question) and the Horizontal Line Break.
     
  1. Any hyperlink used within a KB answer should open in a new window.​​​​​​​
    To have a link open in a new tab:
    Please select the "Target" tab and choose "New Window(_blank)."


Choose the "Target" tab and select "New Window(_blank)."

 

If you need further assistance, please use the following link to contact IT - Submit a service request.

Print Article