Question

• How do I write and submit a knowledge base article?
• What is the knowledge base style guide?

Answer

All staff members with Knowledge Base Create/Edit permissions have the ability to write and submit knowledge base articles. If you would like to request for a new knowledge article to be written and/or request permission to create your own knowledge articles, click this link: Knowledge Base Request.

Writing An Article:
 

1. Review the knowledge base style guide here. This is a mandatory step.
    
2. Prior to creating a new knowledge article the following items should be considered:
   1. Does the knowledge article already exist in the knowledge base for the subject? If an article already exists, then consider only editing the existing article.
       
   2. Use only one knowledge article if you are describing "How to do" something from different platforms or different types of machines. For example: "How do I install (any application) on a Windows PC and a MAC?" Instead of creating two separate articles, only one needs to be created. This is true even if the instructions are different. Just be sure to add anchors to separate the instructions.
       
   3.  Is the content you are going to create "How to do" something, with a step-by-step guide, or is it only information about a product or service? If the content is only informational, in that it describes a product or service, then this information should exist on the UNCW ITS website and not in the ITS Request System knowledge base. The exception to this is if you are creating content that is only for ITS and it provides technical information that would be valuable to technical staff. An example of this might be, server configuration information, security policies, network schematics, etc. If you need to request for the content to be considered for the ITS website please Click Here to submit a request. Otherwise, please proceed to create your "How to" content.
       
3. Go to the "Knowledge Base" Page.

   *Please note: You should frequently click on the "Save Draft" button when creating or editing a knowledge article.

    

4. Select "New Article."
   
    
5. Select the "Category" by clicking on the magnify glass to see the current options. Select the category in which the new article is to be published. There should not be any need to put a Knowledge Article in more than one Category.
   
   Example: If the article is about managing an element of Email, then you would select the Email & Calendar Category. Also, keep in mind whether the article is to be Public or for ITS Only.

   *Please note: Only select one category. An article should never need to be presented in more than one category. If necessary, a shortcut can be added to a different category, which will bring the client to the same knowledge article.

    

6.  Do not adjust the Order field or click to select the Pin Article option. Skip these fields making no changes.
    
7. 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?”
    
8. Now you are ready to create the Body, or content, of the knowledge article. Begin by clicking the "Templates" button. Select the template that should be applied for the article you are writing. Please ensure you are following the style guidelines!
   
   
    
9. Prior to saving the article an update should be made to the "submit a service request" hyperlink, which is the "footer" or the very last verbiage presented in the article.
   
   
   
   The objective is to connect the client to the specific request form they need in order to submit a service request. In order to do this, follow these steps:
   1st: You will need to locate the service catalog item that should be used.
   2nd: Open the service catalog item, and then copy the entire URL string from the search bar.
   3rd: Return to the knowledge base article you are creating/editing and right click on "submit a service request" and click on "Edit Link."
   4th: Highlight and delete the existing URL string, and paste the new URL string that you copied from the address bar.
   
   
    

   *Please note: For articles that are "Public": If there is no service catalog item to refer the client to, then it would be appropriate to remove the "submit a service request" verbiage from the footer. The CHAT with TAC verbiage should never be removed from "Public" knowledge articles.

    

10. In the "Article Summary"" field, please be sure to briefly summarize the important details of your article. For example, you might enter, "New Article for Account Updates."
     
11. In the "Tags" field, create keywords that will help clients easily find the article when they are searching the portal. Typically, tags are words found in the "Subject" description.
     
12. Click on the check box to "Notify Owner on Feedback."
     
13. Are you ready to publish your draft? If you are ready for the content to be reviewed, approved and published, then click, "Yes, my draft is ready to publish." If you still need to add more content, then click "No, I'm still working on it."
     
14. When creating a new knowledge base article, skip the "Knowledge Review Items." These only need to be answered when "Reviewing" a existing knowledge article.
     
15. 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.
   
   
    
2. Font type is Helvetica.
    
3. Font size is 16pt (including the TAC footer).
    
4. Do not use short descriptions on any KB article.
    
5. According to OUR's Brand Identity Guide, we will not use the Oxford comma (which is the comma that comes before the "and" in a series).
   
   Example without Oxford comma: All faculty, staff and students have the ability to favorite a service.
    
6. All KB articles should be “tagged” appropriately.
    
7. 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?
    
8. "ITS Request System" is always upper case.
    
9. Any time "TeamDynamix" needs to be referenced in an article, please call it the ITS Request System instead of "TeamDynamix." 
    
10. Adding a screen shot image requires that the image be saved and uploaded. 

    *Please note: Never copy and paste an image directly into the content section of a knowledge article as it will break TeamDynamix.

    
    To add an image:
    1. Save the image to a folder.
        
    2. After placing your cursor on where you would like to add the image. Click on the image icon in the tool bar.
        
    3. Click on the "Upload" tab.
        
    4. Click on "Choose File" and select the image you saved to a folder.
        
    5. Then click on "Send it to the Server". You will receive a system message indicating the "file has uploaded successfully!" Click on "OK".
        
    6. You will automatically be reverted to the "Image Info" tab. At this point you must enter the Alternative Text and enter "1" in the "Border" field. Then you can click "OK".
        
    We 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.
    
    

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, and then anchor those questions to their related steps (see example KB article below) – Please let Danielle know so she can add anchor code.
   • Multiple questions should use bullet points.
   • Example: https://uncw.teamdynamix.com/TDClient/KB/ArticleDet?ID=12426

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. Steps in KB articles should be grammatically correct and end with the proper punctuation mark.
    
3. 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.
    
4. There should be an extra break / space between each step and a screen shot 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.”
    
5. Proper nouns in steps should use quotes for emphasis, and punctuation marks remain inside the quotes.  
   
   Example: Please select "File," and then select "Save."
    
6. 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).
    
7. 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" above for example).
    
8. 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."
     
     
9. 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)."
   
   
    
10. If you need to add a "please note" the format is:
    • Place your cursor where you would like to add the "Please Note".
    • Go to "Templates."
    • Select "Add Please note:" 
    • Now the verbiage in the Please note box can be modified as needed.
      
      Example:

      *Please note: Only use Please Note when you are attempting to highlight a critical detail for the client that is not necessarily at "How to" step.

If you need further assistance, submit a service request or CHAT with TAC.