CASL KB Style Guide

This guide is here to make writing KB articles easier and to help our articles feel like they came from one team. It covers how we word instructions, what we call things in the interface, how we handle Canvas terms and capitalization, and how to title and summarize an article. Most of it follows the Microsoft Writing Style Guide; where we do something our own way, it's noted. When you're unsure about something not covered here, the Microsoft Writing Style Guide is our default.

How to read this guide: Something about we follow microsoft guide unless otherwise specified. 

Writing Instructions: Order Matters

The biggest thing that makes instructions feel clear is putting what the reader needs to know before the action, not after. A reader who follows along in real time should never do something and only then read the condition that would have changed their mind. Lead with the timing, condition, or location; end with the action.

Do: After you finish grading, press Esc.

Don't: Press Esc after you finish grading.

Do: If you want to keep the draft, select Save.

Don't: Select Save if you want to keep the draft.

Do: In the top-right corner, select Settings.

Don't: Select Settings in the top-right corner.

A companion habit: describe the action, not the interface, when you can. Tell the reader what they're accomplishing rather than over-narrating buttons and colors. Then, when you do name part of the interface, put it before the action (above).

Do: Save your changes.

Don't: Click the blue Save button in the lower-right corner.

Two more habits that keep steps clear:

  • Write steps in the order the reader does them. "On the File menu, select Save" instead of "Select Save on the File menu."
  • Speak to the reader as "you," and give steps as commands. "Select Submit." Use the active voice and present tense.

Documenting the Interface: What Verb, What to Call It

Our articles are worded so they are accurate whether readers are using a laptop or a mobile device. 

Use "Select," Not "Click"

Use select as the everyday verb for choosing a button, link, menu item, tab, or list option. Not because of a style fad, but because many of our readers are on phones and tablets — they don't click, they tap. "Select" is the one word that's true whether the reader clicks, taps, or uses a keyboard. Keep the verb quiet and let the bold label carry the meaning.

Do: Select Submit.

Don't: Click on the Submit button.

The Everyday Verbs

Which verb to use for each action
When the reader… Use Example
Activates a button, link, menu item, or tab select Select Submit.
Types into a field enter Enter your username.
Checks a checkbox check Check the Notify students checkbox.
Unchecks a checkbox uncheck Uncheck the Notify students checkbox.
Opens a menu, pane, dialog, or app open Open the Rich Content Editor.
Flips a toggle turn on / turn off Turn on the Multiple Attempts toggle.
Chooses from a list select From the Term drop-down list, select Fall 2025.
Moves an item by dragging drag Drag the module above the first item.
Expands or collapses a section expand / collapse Expand the Assignment Details section.

Checkboxes: We say check and uncheck — plain words everyone understands. (Microsoft says "select" and "clear," but "clear" reads like "erase," so we don't use it.)

A few words to avoid: click on (just "select"), type in or input (use "enter"), hit a key (use "press"), and navigate to (use "go to").

What to Call Each Control

The right name for each interface element
The element Call it Not
A list that drops open drop-down list dropdown, drop down, pulldown
A box that appears over the page dialog dialog box, pop-up, window
A region within a page pane section, area
Tabbed navigation tab —
A clickable command button (usually drop the word — see below)
A box you type into field box, blank
A small symbol icon (use the Canvas icon name)
An on/off switch toggle switch, slider

Name the Control Type Only When It Helps

Include the type of control (drop-down list, tab) when the reader needs it to find the thing. Drop it when the bold label alone is obvious — that keeps steps clean.

Do: Select Save. (label is obvious, drop "button")

Don't: Select the Save button to save. (cluttered)

Do: From the Term drop-down list, select Fall 2025. (type helps locate it)

Don't: Select Fall 2025 from Term. (confusing without the type)

Menu Paths and Keyboard Keys

For a path through menus, bold each label and separate them with an arrow: File > Save. For keyboard shortcuts, tag each key, one per key: press Ctrl + Shift + R. (Both have buttons in the KB editor tool — you don't have to format them by hand.)

Pronouns and How to Address the Reader

Speak to the reader directly as "you," and for anyone you describe in general — an instructor, a student, a user — always use they / their. Never "he," "she," "his," "her," or "his/her" for a generic person.

Do: If an instructor wants their course copied, they submit a request.

Don't: If an instructor wants his/her course copied…

Do: When a student submits an assignment, they receive a confirmation.

Don't: When a student submits an assignment, he or she receives a confirmation.

Refer to the software by name or as "it," never "he/she" ("Canvas sends a notification"). And avoid speaking as the institution inside steps — write "Save your work before closing," not "we recommend saving."

Canvas Terms and Capitalization

This is the easiest place to slip. The rule: capitalize a word when you mean the Canvas feature; use lowercase when you mean the everyday thing. The same word often changes based on what you mean.

Canvas feature (capitalized) vs. generic thing (lowercase)
Word Capitalized — the Canvas feature lowercase — a generic thing
Gradebook Open the Gradebook. (always capitalized) —
Pages / page Create a new page in Pages. scroll down the page
Assignments / assignment The Assignments page lists all coursework. submit your assignment
Modules / module Modules organizes course content. add the file to the module
Discussions / discussion Post in Discussions. reply to the discussion
Quizzes / quiz Quizzes is in Course Navigation. take the quiz
Files / file Upload to Files. attach a file
Grades / grade Grades shows your scores. enter a grade

A helpful tell: the feature-area name (the things in Course Navigation — Assignments, Pages, Modules, Files) is usually the capitalized one; a single everyday instance (an assignment, a page) is lowercase.

Some Canvas names are always capitalized because they're proper names with no everyday version: SpeedGrader, DocViewer, Dashboard, Rich Content Editor (RCE), Course Navigation, Global Navigation, Inbox, Syllabus, New Quizzes, Classic Quizzes, Blueprint Course, Course Home Page.

When you name a Canvas icon, use its real name — Assignment icon, Attachment icon (the paper clip), Discussion icon (the comment bubble), Quiz icon, Visibility icon (the eye), Warning icon — rather than inventing a description.

Everyday Computing Terms

  • log in / log out are verbs ("Log in to the website"); login / logout are nouns or adjectives ("the login button"). Same for sign in / sign out. Never "log into" or "sign into."
  • email (not "e-mail")
  • website is one word; web page is two; home page is two
  • plugins (no hyphen); add-ons (with a hyphen)
  • Internet is capitalized

Naming UWM and the Universities

  • University of Wisconsin-Milwaukee — hyphen, no spaces. UWM is fine on first reference in KB articles; both UWM and UW-Milwaukee work afterward.
  • Use Universities of Wisconsin (not "UW System") in current references.
  • Lowercase university as a common noun, even for UWM ("the university recently…").
  • What used to be UW Extended Campus (UWEX) is now the Office of Online & Professional Learning Resources (OPLR).

Punctuation, Spacing, and Numbers

  • Use the Oxford comma: assignments, quizzes, and discussions.
  • One space after a period.
  • Percent: use the % sign with a number, no space (95%); add a leading zero below 1% (0.7%). Spell it out in casual phrasing ("a zero percent chance").
  • Phone numbers use hyphens: 414-229-4035.
  • that vs. which: "that" (no commas) for essential information; "which" (with commas) for information you could drop without changing the meaning.
  • Ampersands (&) only in official names or logos — never in place of "and" in a sentence.

Lists

  • Numbered lists for steps that happen in order; bulleted lists for items with no sequence.
  • Never use a single-item list. A list of one is announced to screen readers as "list, one item" — confusing. Make it a sentence, or use the indent style if you just need to inset text.
  • Punctuation: end an item with a period if it's a complete sentence; leave it off if it's a fragment. Be consistent within a list — don't mix.
  • Keep items parallel — start them all the same grammatical way (all verbs, or all noun phrases).

Headings and Structuring an Article

The KB makes your article title the top heading (Heading 1) automatically, so your own sections start at Heading 2. Never put a Heading 1 in the body.

  • Heading 2 for your top-level sections, Heading 3 for subsections, Heading 4 beneath those — always in order, never skipping a level.
  • Break up dense content with headings so readers (and screen-reader users) can scan and jump.
  • Headings use title case — capitalize the major words (the same as article titles). Example: Creating an Assignment, not Creating an assignment.
  • For long, dense reference articles, you can use the H2 Bar style for stronger top-level section breaks — but use it for every Heading 2 on the page or none, and save it for genuinely long pages.

Adding a Table of Contents

The KB can build a clickable Table of Contents for you with Insert > Table of Contents. It pulls your Heading 2 and Heading 3 sections automatically and publishes as the boxed "In this article" panel — you don't type the heading or the box, and there's nothing to style. (This very guide uses one.)

The question is when it's worth it. A Table of Contents earns its place when a reader needs to jump to a section rather than scroll — and on a short article, scanning a list of links is slower than just reading. So:

  • Add one when the article has about four or more sections, or runs longer than a screenful. That's enough structure for the map to be useful.
  • Skip it on short articles — three or fewer sections, or anything a reader takes in at a glance. A three-paragraph article doesn't need one.
  • It's most useful on reference and informational articles people land on to find one specific part (an "Assignments" overview where someone wants just the grading section).
  • It's least useful on simple step-by-step procedures meant to be followed in order — inviting readers to jump around can work against the sequence. A long how-to may still skip it.

Because it builds from your headings, a Table of Contents is only as good as your heading structure — one more reason to use real Heading 2 and Heading 3 levels, in order, rather than faking sections with bold text.

Accessibility Essentials

These are quick to get right and matter a great deal to readers using assistive technology:

  • Every image needs alt text, or mark it decorative if it carries no information.
  • Every data table needs a caption and real header cells.
  • No merged or split cells in a data table — keep it a simple grid. Split a complicated table into two.
  • Never use a table to lay out a page — tables are for data only.
  • Use real headings in order — never make text look like a heading by bolding it.
  • Write meaningful link text — "Register for an accessibility workshop," never "click here" or a bare web address.
  • Never rely on color alone to carry meaning.
  • Avoid all caps. All-capital text is harder to read and can be misread by screen readers, so use normal capitalization.

Titles, Summaries, and Keywords

Titles

Start with the tool name, then a spaced hyphen, then the topic: Canvas - Topic. Add the audience in parentheses when an article is just for one group.

  • How-to / process guides use an "-ing" phrase: Canvas - Creating an Assignment.
  • Overviews and informational articles use a topic noun: Canvas - Course Navigation.
  • FAQs use a topic plus "FAQ": Canvas - Assignment Settings FAQ.
  • Audience-specific articles add it at the end: Canvas - Grading in SpeedGrader (Instructors).

Use title case (capitalize the important words). Question phrasing like "How do I…" belongs only inside an FAQ's entries, not in the title.

Summary

The Summary you enter becomes the article's opening paragraph and the snippet people see in search results — so write it as a friendly first sentence that leads with the topic. Use the pattern that fits the article:

Summary openers by article type
Article type Pattern and example
Process guide "This article explains how to [task] in Canvas." → This article explains how to create and configure an assignment in Canvas.
Troubleshooting "This article provides solutions for [problem] in Canvas." → This article provides solutions for missing student submissions in Canvas.
FAQ "This article answers common questions about [topic] in Canvas." → This article answers common questions about assignment settings in Canvas.
Informational "This article provides an overview of [topic] in Canvas." → This article provides an overview of how assignments work in Canvas, including types and grading.

Keep it to one or two sentences, and don't just repeat the title word for word.

Keywords

List the feature name, the words people actually search for (including other names for the same thing. For example, "course code" is also a "reference code" or "short name"), and the task verbs. Separate them with commas, use lowercase, and don't repeat words already in the title.

When Something Isn't Covered Here

If a situation isn't in this guide, the Microsoft Writing Style Guide is our default. And if you find yourself improvising the same thing repeatedly, let us know. If it's a real recurring need, we'll add it here so everyone benefits.

Style Appendix

A quick visual reference for every theme component. For each one: when to use it, how it looks, and the exact HTML to copy. On the published page, each code block gets a Copy button automatically, or use the KB Styles editor helper, which inserts the same markup for you. Replace the placeholder text with your own.

Callout: Tip

Use a Tip callout for helpful, optional advice such as: a shortcut, a best practice, a nice-to-know. Tips are friendly, not urgent.

Tip: Save your work often because the editor does not auto-save.

Callout: Tip HTML Code

<div class="callout callout--tip">
  <p><span class="callout__label">Tip:</span> Your tip text here.</p>
</div>

Callout: Important

Use an Important callout for something the reader must not miss such as a warning, a required step, a consequence. Reserve it for genuinely critical information so it keeps its weight.

Important: Deleting a course is permanent and cannot be undone.

Callout: Important HTML Code

<div class="callout callout--important">
  <p><span class="callout__label">Important:</span> Your important text here.</p>
</div>

Legacy alert--info, alert--warning, and alert--error classes still render (mapped onto these callout styles), but use callouts for new content.

Procedure Bar: Video

Use a Video procedure bar to introduce steps shown in a video. Place it just before the video or the steps it labels.

Video: Enroll in a course

Procedure Bar: Video HTML Code

<div class="procedure-bar procedure-bar--video">
  <h4>Video: Task name</h4>
</div>

Procedure Bar: Written

Use a Written procedure bar to introduce written, step-by-step instructions. Pair it with a Video bar when you offer both formats.

Written: Enroll in a course

Procedure Bar: Written HTML Code

<div class="procedure-bar procedure-bar--written">
  <h4>Written: Task name</h4>
</div>

Keyboard Keys

Use keyboard keys to show a key or combination the reader should press. Put each key in its own <kbd> and join a combination with a plus sign.

Press Ctrl + Shift + R to hard-refresh the page.

Keyboard Keys HTML Code

<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd>

Inline code

Use inline code for a short snippet inside a sentence. For example, apply this style to a filename, a setting name, a value, a short command, etc.

Open config.json and set debug to true.

Inline Code HTML Code

<code>config.json</code>

Preformatted (code block)

Use a preformatted block for multi-line code, command output, or a template the reader will copy. It preserves spacing and line breaks, and gets a Copy button automatically on the published page. For a short snippet inside a sentence, use Inline code instead.

Example:

cd /var/www/site
npm install
npm run build

Preformatted HTML Code

<pre>cd /var/www/site
npm install
npm run build</pre>

Label Chip

Use a label chip for a small inline tag. For example, apply this style to a status, category, or UI label. It is just decorative emphasis, not a heading.

Course status: New

Label Chip HTML Code

<span class="kb-label">New</span>

Indent

Use indent to offset a block (a paragraph, list, etc.) from the left margin. Apply this style to a nested note or secondary detail under a step.

Step 1. Open the settings panel.

This indented note sits under the step above.

Indent HTML Code

<p class="offset-left-40">Indented text.</p>

Blockquote

Use a blockquote to set off a quotation or an excerpt from another source.

The system will be unavailable Saturday from 2–4 a.m. for scheduled maintenance.

Blockquote HTML Code

<blockquote>
  <p>Quoted text.</p>
</blockquote>

Accessible table (column headers)

Use an accessible table for tabular data. Always include a caption (the table's title) and mark the header row with <th scope="col"> so screen readers announce each column. The wrapper lets a wide table scroll on phones.

Lab software by room
Room Software Seats
BOL 120 SPSS, R 30
BOL 145 MATLAB 24

Table: Column Headers Only HTML Code

<div class="kb-table-wrap">
  <table class="kb-table">
    <caption>Table title</caption>
    <thead>
      <tr><th scope="col">Column A</th><th scope="col">Column B</th></tr>
    </thead>
    <tbody>
      <tr><td>Cell</td><td>Cell</td></tr>
    </tbody>
  </table>
</div>

Comparison table (column + row headers)

Use a comparison table when the first column also labels each row (e.g. comparing options across features). Mark the first cell of each body row with <th scope="row">. Avoid merged cells — they break the header relationships.

Plan comparison
Feature Free Pro
Storage 5 GB 1 TB
Support Email 24/7 phone

Table: Column + Row Headers HTML Code

<div class="kb-table-wrap">
  <table class="kb-table">
    <caption>Table title</caption>
    <thead>
      <tr><th scope="col">Feature</th><th scope="col">Free</th><th scope="col">Pro</th></tr>
    </thead>
    <tbody>
      <tr><th scope="row">Storage</th><td>5 GB</td><td>1 TB</td></tr>
    </tbody>
  </table>
</div>

XYZtable (row headers only)

Content here.

Table: Row Headers Only HTML Code

Content here.

Collapsible Panel (Accordion)

Use a collapsible panel to tuck supplementary content (FAQs, optional detail) behind a clickable title. Add accordions through the editor via Insert > Collapsible Panel rather than typing it. The expand/collapse behavior is added automatically on the published page. It's shown expanded here. Keep the heading level in order with the rest of your page.

What if I forget my password?

Use the "Forgot password?" link on the sign-in page to reset it.

Collapsible Panel HTML Code

<h3 class="panel-head">Panel title</h3>
<div class="panel-content">
  <p>Hidden content.</p>
</div>

H2 Bar

Use an H2 Bar for a bold, full-width section divider (a white-on-teal heading that stands out more than a normal H2). It's still a real H2 in the page outline, so use it for actual sections, not decoration. (Shown as code only here so it doesn't add an extra entry to this guide's table of contents.)

Insert screenshot here

H2 Bar HTML Code 
<h2 class="invertedcolor">Section title</h2>

Headings (H2–H5)

Structure every article with headings in order: H2 for main sections, H3 for sub-sections, then H4 and H5. Don't skip levels, and pick a level for its place in the outline, not its size. The section titles throughout this guide are themselves live examples of Headings 2–4.

Heading 2–Heading 5 HTML Code

<h2>Main section</h2>
<h3>Sub-section</h3>
<h4>Smaller heading</h4>
<h5>Smallest heading</h5>

Image with Standard Border

Give screenshots and figures the standard border so they separate from the page. Add it in the editor via Insert/Edit Image > Advanced (Border width 2, Border style solid), the KB Styles Image border toggle, or the style below. Always write meaningful alt text describing what the image shows.

Image with Standard Border HTML Code

<img src="YOUR-IMAGE-URL" alt="Describe what the image shows"
     style="border-width: 2px; border-style: solid;">

Table of Contents

An "In this article" table of contents is generated automatically when you select Insert then Table of Contents in the editor. It builds itself from your H2/H3 headings when the page publishes, so there's no HTML to copy. (See "Adding a Table of Contents" above.)


Keywords:
standards, style, punctuation, grammar, spelling, format, writing, KB, knowledgebase 
Doc ID:
162069
Owned by:
Katherine P. in CETL Sandbox
Created:
2026-06-18
Updated:
2026-06-23
Sites:
UW-Milwaukee CETL Sandbox