Knowledge Base Style Guide

Purpose 

This style guide is intended to guide the form and structure of any article or page used to assist subject matter experts and technicians in the creation and maintenance of an external-facing knowledge base in the UO Service Portal.

Internally-facing documentation that resides within Confluence adheres to its own style guide. (Requires access to UO Confluence, typically reserved for IT staff.)

Table of contents

• The intent of this guide
• The University of Oregon existing style guide standards
• Article creation and template usage
• Article template descriptions
• Service pages
• Article text style
• Adding alert boxes
• Article content guidelines (non-text) 
• Need help?

The intent of this guide

This guide is meant to act as a framework that will assist information technology employees through the requirements of creating and maintaining a knowledge base and its help articles by both subject matter experts and other technicians alike. This guide is not intended to be fully descriptive or exhaustive in and of itself but is to highlight some specific style elements and to provide access to the resources on which it depends that are described in the University of Oregon's existing style guide standards section below.  

The goals of this guide are as follows: 

1. Creation and maintenance of the knowledge base(s) need(s) to be accessible universally in accordance with WCAG 2.1 AA guidelines and any future updates to that guide as it pertains to text, imagery, and audio and video formats.
2. Videos would need subtitles and/or closed captioning along with audio descriptions of images shown.
3. Forms should include descriptive HTML tags that provide the information needed to submit them.
4. Any attached files would need an alternative text-based format compatible with assistive technologies.
5. To create content that is easy to understand regardless of technical aptitude or ability.

Back to the top.

The University of Oregon's existing style guide standards 

University Communications maintains the Editorial Style Guide that is used for official web communications across all campus departments. This resource is the university authority on any issues involving grammar, punctuation, capitalization, and the like.

• This style guide is based on The Chicago Manual of Style for any style issues not explicitly stated in the Editorial Style Guide.
• Merriam-Webster as the standard dictionary. 

Additional resources used and referenced by this guide are linked below:

• Web Content Accessibility Guidelines, version 2.1 AA Level (WCAG 2.1 AA)
• Guidelines from Digital Accessibility @ UO
• Americans with Disabilities Act (ADA) Web Accessibility Guidelines 
• Knowledge-centered support (KCS) guidelines 
• Writing for the Web (University Communications) 
• University of Oregon Brand and Style Guidelines 

Back to the top.

Article creation and template usage

Articles are created within the UO Service Portal with the use of templates. Templates help to focus content on its intended purpose. Please keep in mind that this is not an exhaustive list of all possible article contents and new templates can be added to this catalog by submitting a consultation request on the Knowledge Management Support service page. 

Any article should have the following: 

1. The intended purpose stating why it was written.
2. The intended audience for whom it was written.
3. Any prerequisites needed for using the article.
4. Prior knowledge, access, or specific tools among others. 
   1. Example: This article is designed to act as an overview of USS Knowledge Management and is intended for all UO faculty, staff, and student employees. Parts of this article require that you have access to a UO Service Portal role capable of editing knowledge base articles.
   2. A section for links to any additional content at the end of the article (from external sources), links to related articles within the UO Service Portal in the Related Articles section (within the article's Related Articles tab), and tagged appropriately as to be associated with related content.

Back to the top.

Article template descriptions 

Below is a list of different templates and their intended uses. To use a template, select the Templates drop-down menu and scroll down to the Structure category within the article editor.

Frequently Asked Questions (FAQs) 

• The FAQ template is designed to familiarize users with known issues for a service in a question-and-answer format.  
• FAQs can stand alone as resource articles but can be incorporated into other article types. 

Getting Started

• The Getting Started template is designed to help orient users to what a service is, define any vocabulary specific to that service, and list its primary functions alongside university best practices.
• Getting Started articles should provide a high-level view of the service and its functions. 

Issue/Cause/Resolution 

• The Issue/Cause/Resolution template is designed like an FAQ article but with an added section to inform the user of the underlying source of the issue along with a resolution to either fix the issue or to implement a workaround. 
• Note: Use this template only when an underlying cause has been verified. 

Process/Procedure 

• The Process/Procedure (or How-To) template is designed to guide users through a specific set of steps that have a known, intended outcome. Examples include software installation and configuration, how to connect an email account to an email application, etc.
• Process/procedure articles are in a list but can be enhanced using guiding screenshots or instructional videos. 

Question/Solution

• The Question/Solution template is designed to guide readers from a question to an answer without describing an underlying cause or as part of a FAQ list.
• Question/Solution articles can stand alone as resource articles but can be incorporated into other article types.

Back to the top.

Service Pages 

The following are the sections that will be included on the service page. This is modeled after the article overview page template described above but modified for service pages: 

Service Description (could be part of an overview as well) 

• Service descriptions will describe the service that is being provided and any description of the system that the service supports will be placed in a related Knowledge Base Article. 
• Directions provide detailed steps that customers will need to follow, and at a minimum, a list of the required information. 
• Directions will be followed by a statement informing the customer of what they can expect once the ticket is submitted.  Any detailed process steps should be placed in a Knowledge Base article and linked to the page. 

Standard Service Features (Overview) 

• Standard service features will list, and describe, individual options that a customer can request. 

Constraints/Scope (Audience, Prerequisites) 

• Constraints will list who will and who will not be able to request the service and any constraints to the service. 
• If there is any cost associated with the service, the costs will be listed. 

Back to the top.

Article text style 

Once an article template is chosen, the content should adhere to the following guidelines. These guidelines are derived from the WCAG 2.1 AA, and the University of Oregon Editorial Style Guide.

Use of heading text 

The text size will follow standards for web documentation: 

• Heading 1 is used for titles of articles only (by default).
• Heading 2 may be used for naming different parts or sections of an article (e.g., Purpose, Components).
• Heading 3 through 7 may be used for identifying subsections. 

Body text and format 

The main body text for the article should be using the Paragraph heading size (by default).

• Bold text should be used to highlight an important note or word germane to the article topic that is of key importance.
  • Example: Use bold when you are trying to direct readers to a specific thing like a menu option
  • E.g., Click OK, Select File, then Save As... 
  • Note: do not use quotation marks for this purpose unless they are used for any specific quotation from another source.
• Italic text may be used to emphasize words like bold text, but it is typically used particularly in conveying meaning
  • Used for words or terminology from another language conveyed alongside English words in English grammar and syntax
• Underlined text may be used to highlight important pieces but should only be used sparingly since it can be confused with hyperlinked text
• Any hyperlinked text should be a descriptive phrase or sentence instead of a URL
  • Example: The Chicago Manual of Style is one of the style resources for the university.
• For Command Prompt and Terminal-based commands, use Computer Code (found in the Style drop-down menu of the editor)
• Tabulation and indentation of text are not necessary to define paragraphs as in other writing styles due to the use of web heading text
  • Tabulation and indentation are used primarily for making lists, determining a hierarchy, or denoting quoted text
  • Use bulleted lists for unordered lists (e.g., checklists without a specific order)
  • Use numbered lists if the process requires a specific order (e.g., software installation process lists)
• If images are required to assist in greater understanding (i.e., complex software installations, navigating an application, etc.), ensure that they are web-accessible: use annotations and incorporate alt text. (See the Images section below)
• When using numbers in text that are ten or less, please write out the word
  • E.g., eight and not 8
• When referencing file extensions, use an acronym as opposed to a literal file extension unless it is necessary for providing clarity
  • E.g., PDF file and not Portable Document Format (PDF) file or *.pdf
• Use only one space after any punctuation mark, not two.
  • Exceptions to this are:
    • At the end of a paragraph (no space is required)
    • While using hyphens (no space is required)

For more information, please consult the Editorial Style Guide and Writing for the Web guides or submit a question through the Knowledge Management Support service page.

Back to the top.

Adding alert boxes

Alert boxes are used to highlight information of varying degrees to our customers. In the UO Service Portal, alert boxes can be added to any article by using the Templates drop-down menu and selecting the appropriate Formatting option. These are derived from Bootstrap Alerts code that is compatible with TeamDynamix.

When inserting the alert, the template will create an extra space below so that you can click out of the alert panel when you're creating an article. This is to ensure that the panel is formatted correctly when inserted. Remove the space once you're done editing.

Back to the top.

Article content guidelines (non-text) 

Use of non-text content 

Non-text content (images, audio, and video) are required to follow the WCAG 2.1 AA standards.

Use of Font Awesome icons

When using Font Awesome icons for semantic understanding (as seen in the Data Security in UO Collaboration Tools article), you will need to modify the aria-label value in the article's source editor from "icon" to what you intend it to convey.

• For example, if you want to use a check mark icon to convey yes:
  • Select the Source icon in the editor
  • Find the icon's line of code and find the aria-label value
  • Then exchange the term icon with yes 
  • Click Submit Article, Update Article, or Save Draft to save the changes
• For more information, please consult Font Awesome's Accessibility article under Manually Make Your Icons Accessible
• Additionally, if you are unsure, please submit a ticket through the Knowledge Management Support service page.

Use of images in articles 

Images used in an illustrative fashion in articles, help pages, or procedures need to be annotated to guide users and administrators through any steps requiring them while being in compliance with web accessibility standards, namely, the use of alt text for users who use assistive technologies for computing (screen readers, etc.). The alt text field for the image needs to describe the image in a short phrase or sentence and is located under the title for the image file within the image properties dialog box. 

For more information on image usage, please consult the WCAG 2.1 AA Standards.

Use of navigational tabs in articles

Navigational tabs (also called navtabs) are a way to display a list in a tabulated format. When a tab is selected or active, only its contents will be visible. Other tab content will be hidden until its tab is selected or active.

Use of audio and video in articles 

• If audio is created, then used in an article:
  • Ensure that the quality of the audio is high enough to ensure that it is easily heard and understood.
  • Incorporate a transcript for the audio to comply with web accessibility standards. (An audio recording of an article being narrated will suffice.)
• If video is created, then used in an article:
  • Ensure that there are subtitles or closed captions incorporated to describe any audio used throughout the video’s duration including when music or background noise is present.  

For more information on non-text content, please consult the WCAG 2.1 AA Standards 

Back to the top.

Need help?

Please submit a ticket through the Knowledge Management Support service page.