Accessibility
If content isn't accessible, it isn't useful. At Thomson Reuters, we take the Web Content Accessibility Guidelines (WCAG) seriously.
All
of our help content must comply with the Accessibility for Ontarians with Disabilities Act (AODA).Refer to our Digital Accessibility Center of Excellence for guidance and updates on our AODA adherence. You should also be familiar with:
These resources are comprehensive, so we've summarized the key points most relevant to our writing.
Use meaningful titles, headings, and links
- Titles:Keep them short, descriptive of the content, and distinguishable from other pages. Put the unique and more relevant information first.
- Headings:Keep them concise. Use them to group related content and clearly describe each section.
- Links:Make link text describe the destination. Avoid using ambiguous text like "click here" or "read more".
Avoid visual references
Describe user interface (UI) controls by their visible name or hover text, not just their appearance or location. Don't rely on sensory characteristics like shape, color, size, location, orientation, or sound.
This helps people that are blind, color-blind, or have low-vision, and it also accounts for how different screen sizes or zoom levels can change or reposition UI components.
Avoid microaggressions
Microaggressions aren’t usually intentional, but they create environments that exclude people from marginalized communities. In writing, this can look like using stereotypes or phrases with harmful origins. Even if certain words seem harmless, our goal isn’t just to avoid offense. We want to write for everyone.
Some terms and phrases are unavoidable. We have to write help content that matches button text and other UI. But where possible, we want to avoid these terms.
Example words or phrases to avoid | Alternative | Reason |
|---|---|---|
master list, master document | primary list, main document | "Master" echoes language rooted in slavery, so it can marginalize and harm readers. |
blacklist, whitelist | blocklist, allowlist | Tying "black" to bad and "white" to good reinforces harmful racial associations. |
view, watch, see | open, read, access | These verbs assume visual ability. However blind or low-vision users can still do these things, just in a different way. We should avoid these terms, but we don't need to eliminate them if they're accurate. |
click | select, choose | "Click" assumes a mouse. This can exclude mobile, keyboard, and assistive-technology users. |
"it's easy to...", "you can quickly..." | "in a few steps, you can..." | Being more specific explains what makes the process easy without leaving out people with different abilities. |
File | Setup, File > Setup | File , then Setup , or use the <menucascade> element (for AEM Guides authors only). | Not all screen readers can associate | or > with a sequence of buttons or a path. It will read like "File, greater than, Setup, greater than..." or "File, vertical bar, setup, vertical bar...". If Guides authors use the menucascade element in AEM, screen readers will properly read the ">". |
Tables
Tables organize information in a grid of headers, rows, and columns so you can understand how everything connects. To make sure screen readers can understand that structure, you need to use HTML markup for the headers, rows, and cells. Always use the built-in table tool to make sure the markup is present.
Keep tables simple. Complex tables are harder to interpret. It's usually better to break up complex tables into simple individual ones. Simple tables have:
- 1 header row,
- 1 column header (if needed),
- no empty cells,
- no merged table cells.
Images and alt text
Our overall strategy on images is if it doesn't add anything new or specific to the content, we don't need it. However there are times you can benefit from adding images.
Every image needs alt text
code
, but the actual text you include depends on the image's purpose.Images are either Informational, Functional, or Decorative and each one uses a different type of alt-text.
- Informational
- These images share information: screenshots, charts, graphs, infographics, or icons that include text.
- Write alt text that captures the meaning of what’s shown, don't just describe the picture literally.
- Learn more on W3C's Informative Images page.
- Functional
- These images initiate actions rather than share information. They are typically links, buttons, image maps, icons.
- Write alt text that says what the image does, not what it looks like.
- Learn more on W3C's Functional Images page.
- Decorative
- These images don't add information to the page. In our case, that usually means the surrounding text already covers it.
- Think of them as visual support for content that might be tricky to explain.
- Use an emptyalt="". The attribute still needs to be there.
- Learn more on W3C's Decorative Images page.
Most alt-text is 3-8 words, but can go up to 15-20 words (100-125 characters). Going any longer isn't recommended.
If you're having trouble deciding on alt text, ask yourself these questions:
- What function does this image play?
- What message am I trying to convey?
- If the description is over 100-125 characters, should I take the info out of the image and include it in the body.
- Does the alt-text begin with a capitalized word? It should.
- Are there any alphanumeric characters? Screen readers can't read these.
PDFs
We generally don't recommend using PDFs for help content. However there are times when PDF format makes sense. If we do publish a PDF, it needs to be accessible.
If you've checked with the Content Strategy and Design team and agreed a PDF is the right choice, the easiest way is to start in Word and convert it to a PDF. Word has built-in formatting for headers, tables, images, and lists that is needed for accessibility.
Both Word and Adobe have accessibility checkers - use them. They're helpful, but they won't catch everything. You'll need to do a manual review as well. If you need help with this, check out our company guide on making PDFs accessible.
Related Content
-
Introduction
Format:
Article,
2 min read
-
Images
Format:
Article,
2 min read
-
PDFs
Format:
Article,
1 min read