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 & Text Formatting

Images

Notes & Callouts

Bullet & Number Lists

Hyperlinks

References to the Service Center

Articles, categories and subcategories

Change Management
 

Article Titles

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

Heading Formats

Font & 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 & 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:

NOTE: As a security measure, your responses to challenge questions are not viewable after saving your responses.

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 & 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.

Changes made during the academic year
  • New categories or subcategories
  • New articles
  • Updated information / procedures
  • Updated screenshots
  • Corrections - typos, etc.
Changes NOT made while classes are in session
  • Category / subcategory name changes
  • Rearrangement of categories / subcategories
  • Rearrangement of articles into different categories or subcategories
  • Retirement / archiving of an article
Was this helpful?
0 reviews

Details

Article ID: 136175
Created
Fri 1/14/22 2:28 PM
Modified
Wed 1/25/23 3:33 PM