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

Please Note: This is a living document. If you see anything that needs to be amended, please submit a ticket on the Knowledge Management Support service page or select Create a Ticket on this page.

Table of contents

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.

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

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.

Article Creation From Tickets

  • Nearly identical to the Issue/Cause/Resolution template with Environment added. Environment pertains to the device, its administration (personal or managed) and operating system.
  • This template extracts the title, description, and resolution fields from a ticket when the Create new article option is selected during a ticket update.

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 images, screen capture images, or instructional videos as needed. 

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
    • Note: Do not use quotation marks for this purpose unless they are used for any specific quotation from another source.
  • 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.
  • 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)
  • When using numbers in text that are ten or less, please write out the word
    • E.g., eight and not 8
  • When writing the word and, do not use the ampersand (&) symbol.
  • 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.

Do I?: Enter a question to be answered for next steps.
Success! Please enter your success text to indicate a successful or positive action.
Please Note: Insert note text here.
Note: Enter note text here.
Warning! Enter any warning text that indicates a dangerous or potentially negative action.

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 or its conveyed meaning in a short phrase or sentence and is located under the title for the image file within the image properties dialog box.

  • Avoid using image of or a similar phrase. By inserting alt text, it’s already implied that there’s an image there.
  • If the image is purely decorative, alt text is not required. A screen reader will pass over it.

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.

Ensure that you are using the Navtabs template from the Templates drop-down menu in the editor.

Once entered, you can create and edit tab content by:

  1. Clicking directly on the tab to edit its name.
  2. Entering the body text for the tab below.

Select Update Article or Save Draft to save changes.

Follow the instructions to delete an(y) extra tab(s):

  1. Select Source from the article editor
  2. Look for the <div> tags with the tab(s) you wish to remove. They are in two locations.
    1. Delete the tab(s) from the <div role="navigation"> section indicated by <li> tags and delete the <li> tags and content.
    2. Scroll down to the associated tab <div class="tab-pane fade tab-#" id=".tab-#" role="tabpanel"> tags and delete the associated tags and content for each tab.
    3. Ensure that the aria-controls tag parameter matches the tab title.
      1. For example, the Delete the extra tab(s) tab label has an aria-controls value of Delete the extra tab.
    4. Be careful not to delete the last </div> tag as it is for the whole content container.
  3. Select Source to go back to the visual editor, and the tab(s) will be gone.

To determine which tab appears first when someone reads the article:

  1. Select the tab to make it active from the editor view,
  2. Then, select Save.

For more information on tabs, submit a ticket to Knowledge Management Support

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.

Print Article

Related Articles (6)

Adding anchors and a table of contents to an article
How do I add anchors to make a table of contents in an article?
Article creation from a ticket
What are the steps needed to create an article from a ticket?
Creating a knowledge base article
Instructions on how to create a new knowledge base article.
Knowledge Base Article Requirements Rubric
This article is designed to act as a rubric for quick reference for any UO Service Portal content creators and authors and is derived from the Knowledge Management Style Guide.
Knowledge Base Glossary of Terms
This article is designed to act as an appendix to the Knowledge Base Style Guide for clarifying the spelling and usage of any commonly used terms within IT specifically and the university more generally.
Maintaining and editing knowledge base articles
This article is intended to provide users within the UO Service Portal that have the ability to create, edit, and publish knowledge base articles.