KB: Usage Guide

Last Updated

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
Example of the heading level controls in the Knowledgebase's text editor
Example of the heading level controls in the Knowledgebase's text editor


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.
    Highlighted text
    Highlighted text
  2. Select the link icon located at the top of the text box area.
Toolbar with link icon highlighted
Toolbar with link icon highlighted

3.        Paste the link in the URL spot and click Link.
Hyperlink popup box
Hyperlink popup box


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