KB: Usage Guide

This guide is intended to ensure the consistency, readability, and accessibility of Knowledge Base articles.  Adherence to these guidelines is a necessary step toward achieving compliance with accessibility standards and making Knowledge Base content accessible to a wide variety of campus audiences.

Quick Reference

Following is a concise summary of key practices. See the relevant sections below for further detail and context.

• Keep it simple! Break long content into short sections, use lists where appropriate, and define technical terminology.
• Be consistent.  Follow the language and formatting standards in this guide to give users a consistent experience.
• Check your heading structure. Use built-in heading levels (Heading 2, Heading 3, etc.) to break up article content, and make sure the outline of headings, subheadings, and sub-subheadings is logical across the entire article.
• Add alternative text to images. Be descriptive of what the image means in context. If someone can’t see the image, what do they need to know about it?
• Be descriptive when adding links. Generic labels like "click here" or "read more" carry no meaning when read by a screen reader. A good label includes the action: "Contact the Chair," "Apply for the Cheer Award," etc. 
• Be sparing with bold and italics. A few words here and there are fine, for emphasis. Whole paragraphs of text in bold or italics are difficult for many users to read.
  
  

Language

• For general-audience articles, aim for an eighth-grade reading level
• Explain technical terms and spell out acronyms on first use (e.g. Learning and Technology Services (LTS))
• Capitalize the first letter in every step
• Write button text exactly as displayed in the application
• Use action words consistently:
  • Click – single action mouse commands.  Buttons, links, etc. (e.g. Click the Start button.)
  • Select – use in menus: dropdowns, radio buttons, checkboxes (e.g. Select Other.)
  • Press – any keyboard command (e.g. Press [Enter] on the keyboard)
  • Type – use when indicating words that need to be entered (do not write "Enter…") (e.g. Type your username and password.)
  • Highlight – used for selecting a section of text
  • Drag and Drop – Separate “thing” from destination (e.g. Drag the Internet Explorer icon and drop it in the Recycle Bin.)
    
    

Layout

• Aim for function over design. The primary purpose of a Knowledge Base article is to convey complex information in as straightforward a way as possible.
• A good article has a well-defined heading structure, uses short paragraphs, and incorporates lists to break down procedural steps.
  
  

Title

• Title format:
  Application Version/Subject: Topic Title
  (e.g. Word 2024: Creating a Table of Contents, or Email: Recover Deleted Items)
  
  

Introduction

• Include any explanatory text on the article topic in one or more paragraphs at the start of the article.  Do not include this information within steps.
  
  

Headings

• Use headings to group relevant information, guide the reader, and break up large blocks of text
• The table of contents will be generated automatically from the heading outline
• Use a well-formed heading hierarchy (i.e. do not skip heading levels)
  • Heading 2 for section titles
  • Heading 3 for section subtitles
  • Heading 4 for additional topic sections, if necessary 
• Do NOT bold or italicize headings

FAQs

Standalone article

• Use appropriately nested headings for FAQ questions
  • A table of contents will automatically be generated from all headings
• Type all questions as regular sentences, with punctuation and sentence capitalization
  
  

Within an article

• Begin the FAQs section with an appropriate (sub)heading
• Format the FAQs as a bulleted list, with the question in bold (do not use headings)
• Example:
  • What does FAQ stand for?
    Frequently Asked Questions
  • Should in-article FAQs be formatted as headings?
    No.
    
    

Formatting

• General:
  • Avoid long passages of bolded or italicized text. Excessive formatting makes content difficult to read for many users.
  • Avoid using bold or italics in headings.
• Additional notes, warnings, and hints:
  • Use a carriage return ([Shift + Enter]) with an additional carriage return after the note.
  • Entire note, warning, or hint sentence should be a italicized, with the title in all caps.
  • Optional steps should include (Optional) at the beginning of the heading/step (e.g. (Optional) Next step here).
  • Example:

1. Click Save.
   NOTE: Failing to click Save in this step will result in a loss of work.
   
2. (Optional) Next step here.
   
   

• Standardized formatting for directions within articles:
  • Use no style when referencing a button that has no text, even when hovered.  Where possible, include an image of the button.
    Ex: “Click the arrow button”
  • Use bold when referencing a button that includes text, or displays text when hovered.
    Ex: “Click Save”
    Ex: “Click the Windows 11 Start button”
  • Use italics when referencing an area (pane, menu, window, section, etc.)
    Ex: “Scroll down the page to the Images section.”
  • Use bold + italics for selectable items within dropdowns, radio buttons, checkboxes, or tables.
    Ex: “Click the Start menu.  Select Control Panel.”
  • Use [brackets] when referencing keyboard shortcuts or keyboard commands.
    Ex: “Press [Ctrl + Alt + Delete]”
    Ex: “Press [Enter] on the keyboard.”
    
    

Links

• Use appropriate labels that describe the destination or action of the link; avoid generic labels like “click here” or “learn more”
  • Assistive technologies (such as screen readers) present users with a list of links on the page; generic link labels lack context
  • Good link examples:
    “Contact the Chair”
    “Fill out the wellness survey”
    “Visit the archives”
• Do not use bold or italic formatting on links
  
  

Creating Links

1. Click and drag over the text you wish to make a link.

   

2. Select the link icon located at the top of the text box area.

3.        Paste the link in the URL spot and click Link.

Images

• Images should be used to illustrate information within the article text.  They should never replace article text.
  • Users of assistive technology, or users who are unable to load images, must be able to follow article text without relying on any images
• Where possible, include an image next to article text referencing icons or buttons that have no text labels
  • Ex: “Click the Chrome Settings button <image>”
• Images used to clarify a step should be added at the end of the step text, on its own line
• Images used to illustrate multiple steps should appear after the steps
• Leave extra space below images to separate them from following text
• Most images should be 500px wide or smaller, unless downsizing would lose necessary details
  
  

Captions / Alt Text

• All images must have a caption.  The caption will serve as both a visual description and an alternative text (“alt text”) for assistive technologies.
• Captions must be reasonably descriptive of what the image means in context
  • Keep in mind that assistive technologies (such as screen readers) cannot “see” the image and will only read the caption
  • Do not begin captions with “Image of” or “Picture of”
  • It is acceptable to begin captions with “Screenshot of,” if appropriate
  • Bad alt text examples:
    “Screenshot”
    “Editing Toolbar”
    “Footbridge”
  • Good alt text examples:
    “Screenshot of the application login screen”
    “Editing toolbar with formatting options highlighted”
    “Campus footbridge showing heavy foot traffic and cracked concrete” (context: page describing renovation plans)
  • More information on writing helpful alt text
• Do NOT embed images containing primarily text content, as this content will be invisible to assistive technology and may become difficult to read on small screens
• Where images have complex information (e.g. infographics, posters, detailed screenshots), be sure to fully describe relevant information within the article text