Accessibility
Keep every page usable with a screen reader: descriptive titles and links, no directional language, alt text, and explicit instructions.
Some readers use a screen reader, some navigate with the keyboard, and some do not distinguish colors. The rules on this page keep the documentation usable for all of them. They follow the Web Content Accessibility Guidelines (WCAG) 2.2.
Write a descriptive, unique page title
The title identifies the page in search results, in the browser tab, and in a screen reader’s page announcement. A generic title identifies nothing there, and two pages with the same title are indistinguishable. Put the most specific information first, and never reuse a title.
- Incorrect:
Troubleshooting - Correct:
Troubleshoot DNS resolution errors
Use one H1 and do not skip heading levels
A screen reader user navigates from heading to heading, so the heading outline works as the page’s table of contents. The title field in the frontmatter renders as the page’s only H1. Start the body at ##, and advance one level at a time. A jump from ## to #### implies a level that does not exist, and the outline loses its structure.
The full heading rules are in Headings.
Write link text that names the destination
A screen reader can present the links of a page as a list, out of their sentences. In that list, “click here” and “read more” name nothing, and every generic link sounds like every other. Use the destination page’s title as the link text.
- Incorrect:
For the length caps, [click here](/en/documentation/style-guide/writing/sentence-structure/). - Correct:
The length caps are in [Sentence structure](/en/documentation/style-guide/writing/sentence-structure/).
The formatting rules for links are in Text formatting.
Do not use directional language
”The box on the right” and “the section below” describe a position. The position changes with the screen size, and it means nothing to a screen reader, which reads the page in one order. Name the element or the section instead.
- Incorrect:
Click the button below. - Correct:
Select **Save**. - Incorrect:
See the section above. - Correct:
Refer to the Prerequisites section.
Write alt text that describes what the image conveys
Alt text replaces the image for a screen reader user. Describe what the image conveys and why it is on the page, in under 150 characters. For a complex diagram, put the full description in the prose around the image and keep the alt text short.
Do not open with “image of” or “picture of”: the screen reader already announces the element as an image. Use empty alt text (![]) only for a purely decorative image. Do not stuff keywords, because alt text serves the reader, not the search ranking.
- Incorrect:
 - Incorrect:
 - Correct:
Do not rely on color alone in diagrams
Color does not reach every reader: many readers do not distinguish it, and a screen reader does not announce it. In a diagram, use labels or shapes in addition to color, and write the legend with names, not colors.
- Incorrect:
The green boxes are the cached responses. - Correct:
The boxes labeled "cache hit" are the cached responses.
Expand acronyms on first use
Spell out each acronym at its first use on every page, because a reader lands on any page directly. The full rule is in Word choice.
Write explicit instructions
An instruction names the control and the action, because “save your changes” leaves the reader to search the screen for the control. When an input has a format or a limit, state the requirement in the step.
- Incorrect:
Save your changes. - Correct:
Select **Save**. - Incorrect:
Enter a value. - Correct:
Enter the TTL in seconds.