Knowledge Base Style Guide

In an effort to maintain consistency across the look and feel of Knowledge Base content, article editors should strive to adhere to the following style guidelines:

Article Titles

Heading Formats

Font and Text Formatting

Images

Notes and Callouts

Bullet and Number Lists

Hyperlinks

References to the Service Center

Articles, Categories and Subcategories

Change Management
 

Article Titles

Write titles as “Actionable Items” in title capitalization (e.g., Working Remotely with Avaya Agent Desktop, Creating Porches Announcements, Making Copies on a Campus Printer, etc.).

Heading Formats

• Normal:  Article content
   
• Heading 1:  Article titles (default)
   
• Heading 2: In general, use H2 for all main headings
   
• Heading 3: Appropriate for subheadings
   

Font and Text Formatting

• Use default font type and color and avoid applying fonts like Times New Roman, etc.
   
• Use the formatting toolbar to format bullets and numbers; DO NOT manually type bulllet and number lists
   
• Use bold type to represent on-screen text / options within directions (e.g., "Click the Edit Layout button")
   
• Avoid using underline - it looks too much like a hyperlink!
   

Images

• Use clear images and avoid blurry ones. Also consider adding a thin outline border when necessary (this can be accomplished in PowerPoint or Snagit).

• Avoid hand drawn shapes when emphasizing screen shot images. Use a rectangle or a circle / oval:

• Applications like the Windows Snipping Tool or Snagit are great screen capturing tools. PowerPoint and Snagit can be used to enhance images with arrows, circles, rectangles, etc.
   

Notes and Callouts

To highlight particularly important or often overlooked content / instructions / warnings, use the Special Container formatting (when appropriate). Use the standard font (normal style) for all text. For example:

As appropriate, use title / headings such as CAUTION, WARNING, ATTENTION, SPECIAL NOTE, READ THIS, DON’T FORGET!, Don’t see what you’re looking for?, Still having issues? Don’t see your device?, etc.). Try to title it in a way that calls out WHY we’re escalating this particular piece of info.
 

Bullet and Number Lists

• Standalone lists (e.g. jump links at the top of an article that mimics a table of contents) do not require bullets
   
• Use numbering for 2 or more step procedures
   
• Consider adding a soft carriage return <SHIFT> <ENTER>  between bulleted / numbered items for extra spacing, if needed, to make text more readable
   

Hyperlinks

• Links within a sentence or paragraph do not require the >> after the link label
   
• Make sure link titles are descriptive
   
• Avoid labeling a link with text like “click here” that doesn't clearly indicate the destination of the link
   

References to the Service Center

• In general, don't include IT Service Center contact information within articles (i.e. Contact the UDit Service Center at (937) 229-3888 or complete a Service Request form for questions regarding user license requirements), since this information is automatically included on the footer of every service catalog page
   
• Make sure contacting the IT Service Center is fundamental to a process (i.e. https://udayton.teamdynamix.com/TDClient/1868/Portal/KB/ArticleDet?ID=46762)
   

Articles, Categories and Subcategories

• Categories at the root level have an icon and short description
  
   
• Subcategories should include a short description and no icon
  
   
• In general, short descriptions are not required for articles that have a self explanatory title (e.g. “Using the Portal Manager to download software on your UD-managed computer” does not require a short description.  Less clear titles (e.g. “Software at UD”) may benefit from a short explanation clarifying the contents of the article.
  
  
   

Change Management

The following table defines the types of Knowledge Base changes that are generally made / not made while classes are in session.