KB Formatting Standards

Overview

This article covers the formatting and style standards for all Knowledge Base articles. Following these standards ensures a consistent, accessible experience for all users. For a quick overview of the most important practices, start with the Quick Reference section below.

Quick Reference

The 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 provide 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. Describe 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)

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 — 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 FAQ 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.

FAQs Within an Article

• Begin the FAQs section with an appropriate (sub)heading.
• Format 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.

Notes, Warnings, and Hints

• Use a carriage return ([Shift + Enter]) with an additional carriage return after the note.
• Bold and capitalize the entire lead-in phrase (e.g., NOTE:, WARNING!, or HINT:)
• Optional steps should include (Optional) at the beginning of the heading or step.

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

• 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. Select the text you wish to link.
2. Click the link icon located in the content editor toolbar.
3. Paste the link in the URL field and click Save.

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.

Alt Text

• All images must have alt text. Alt text serves as both a visual description and an alternative text for assistive technologies.
• Alt text must be reasonably descriptive of what the image means in context.
  • Assistive technologies (such as screen readers) cannot "see" the image and will only read the alt text.
  • Do not begin alt text with "Image of" or "Picture of."
  • It is acceptable to begin alt text 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.

Voice and Tone

Write in a direct, active voice. Avoid passive or overly cautious language.

Examples

Instead of: "Users might want to consider enabling notifications."
Write: "Enable notifications to receive important course updates."

Instead of: "It is recommended that faculty members should review student submissions."
Write: "Review student submissions within 48 hours."