Write for Accessibility
On this page
Writing with accessibility in mind improves the documentation experience for all our users.
Avoid unnecessary font formatting. (Screen readers explicitly describe text modifications.)
Don’t force line breaks (hard returns) within sentences and paragraphs. Line breaks might not work well in resized windows or with enlarged text.
Avoid camel case (
camelCase) and all caps (ALLCAPS). Some screen readers read capitalized letters individually. Some languages are unicameral; they don't have lower and upper cases.Depending on the screen reader (or personal settings), not all punctuation marks are read. Make sure the same meaning is conveyed to the reader without punctuation marks. For that reason, avoid the use of exclamation marks, question marks, and semicolons.
Don't use & instead of and in headings, text, navigation, or tables of contents; however, it's OK to use & when referencing UI elements that use &, or in table headings and diagram labels where space constraints require abbreviation. And of course it's fine to use
&for technical purposes in code.
Provide Context for UI Elements
Don't identify UI elements using only one sensory characteristic (such as color or location).
Directional phrases like “at the top of the page” or "right-hand side" might not provide adequate information to someone using a screen reader. Even relating one element to another with phrases like “next to” or “above” might not provide the correct context.
When referring to a UI element in a procedure, use previous steps to clearly navigate the user to the element to maintain clarity and avoid wordiness. If the same icon, button, or element appears on the page more than once, be more descriptive by using section, modal, or panel headings and field names.
If a UI element is hard to find, provide a screenshot.
Use the label of an element and not its shape or color to describe it.
Use | Avoid |
|---|---|
Click Save. | Click the green button. Click the round button. |
Where an element appears more than once in the UI: 1. Click Clusters. 2. Click ... next to the cluster you want to modify. Where an element appears once in the UI: 1. Click Clusters. 2. Click .... | Where an element appears more than once in the UI: 1. Click .... Where an element appears once in the UI: 1. In the clusters view, click the ... button next to the cluster you want to modify. |
Write for Ease of Reading
Break up walls of text to aid in scannability. For example, separate paragraphs, create headings, and use lists.
Use shorter sentences. Try to use fewer than 26 words per sentence.
Define acronyms and abbreviations on first usage and if they're used infrequently.
Use parallel writing structures for similar things. For example, start each list in the same format.
Place distinguishing and important information of a paragraph in the first sentence to aid in scannability.
Use Descriptive, Hierarchical Headings
Users of screen readers often scan a page by jumping from heading to heading. Make the hierarchy clear and headings meaningful.
Use descriptive headings and titles because they help a user navigate their browser and the page. It's easier to jump between pages and sections of a page if the headings and titles are unique.
Use a heading hierarchy and don't skip levels. For example, put an
h3only under anh2.Don't use a heading level that doesn't fit the hierarchy. Find another way to change the visual formatting of a heading.
Don't have empty headings or headings with no associated content.
Format headings using RST markup, like heading types, not bold.
Use an
h1for the page title or main content heading.
Use Meaningful Link Text and Formatting
Some people who use screen readers jump from link to link to scan a page and need to understand what a link contains.
Use meaningful link text. Links should make sense when read out of context.
Don't use click here or read this document. These phrases provide no information about what a link contains.
Use an external link icon to indicate that the link opens in a new window or tab.
Avoid adjacent links or put a character in between to separate them.
If a link downloads a file, the link text must indicate this action as well as the file type.
Use Alternative Text for Images
Screen readers read alternative text aloud so that users can better understand an on-page image.
Provide alternative (
alt) text that adequately summarizes the intent of each image. Don't describe the image in detail.Don't present new information in images; always provide an equivalent text explanation with the image.
Don't repeat images unless absolutely necessary.
Don't use images of text, code samples, or terminal output. Use actual text.
Use SVG instead of PNG if available. SVGs stay sharp when you zoom in on the image.
Caption Videos, Recordings, and GIFs
Provide captions, transcripts, or descriptions of audio and video content. For example, you can use the autocaption feature in YouTube. Make sure that captions can be translated into major languages.
Avoid flickering or flashing elements. They can cause anything from motion sickness to a seizure.
Use Simple Tables
Don't use tables unless it's the best method to present your information. Tables are challenging for screen readers. If you must use a table, use a simple table that doesn't have cells that span columns or rows.
Avoid tables in the middle of a numbered procedure.
Format a Page for All Abilities
Make sure that your document conveys all the information you intended if you view it in the following contexts:
Without sound
Using only sound
Without color
Using a keyboard
With screen magnification
Without punctuation
Don't use color, size, location, or other visual cues as the primary way of communicating information.
If you're using color, icon, or outline thickness to convey state, then also provide a secondary cue, such as a change in the text label.