Originally published at https://ninadpathak.com/articles/documentation-accessibility-checklist/.
Accessibility testing matters for documentation because a page can look finished and still leave a reader unable to complete its task. A bold heading, a link named “here,” or a screenshot holding the only success signal can turn setup instructions into a visual-only path.
Use this release checklist when you need to decide what to automate, what needs manual testing, and which failure should block a documentation deploy. I built and ran a documentation accessibility checker against a broken fixture and its repaired version so the human review can focus on the experience a parser cannot judge.
Accessibility testing checklist for a documentation release
Run this table against generated HTML and the rendered page. It separates repeatable source failures from the reader-path checks that only a person can complete.
| Page element | What must survive | Quick check |
|---|---|---|
| Heading | Section structure | One page title, ordered heading levels, and no headings created only with visual styling |
| Code | Copyable instructions | Actual text, a declared language, a starting state, and an observable result near the command |
| Link | Destination and behavior | Link text names the destination and signals a download, new tab, or same-page jump when that behavior matters |
| Table | Relationships between values | A simple data table has headers, and layout is not built with table markup |
| Visual | Information beyond pixels | Meaningful images have useful alternatives, decorative images have empty alternatives, and complex visuals have nearby equivalent detail |
| Rendered page | Keyboard and zoom use | Focus remains visible, interactive controls work from a keyboard, and reflow does not hide the task |
Download the documentation accessibility checker (.zip)
The script is deliberately narrow. It flags missing image alternatives, vague links, heading jumps, tables without header cells, and code elements without a language class.
Test documentation structure before visual styling
A documentation page needs structure that exists in the document model, not only in its theme. Google’s accessibility guidance recommends descriptive headings in a logical hierarchy, and Harvard’s structural guidance makes the consequence clear: assistive technologies can navigate structure only when the markup carries it.
Use headings to expose the task route
Keep one page title, then use heading levels to describe the task in dependency order. A level should never be selected for its font size because CSS can change appearance without breaking the document outline.
Read the headings without their paragraphs. A reader should be able to tell where to begin, what action follows, and where to verify success.
Keep lists and tables semantic
Use a list when several items belong together and a table only when readers need to compare consistent fields. A data table needs header cells, and a table used for visual layout invents a relationship that a screen reader will announce as data.
Microsoft State University’s checklist recommends simple tables with row and column headers. If the relationships cannot be stated clearly in headers, split the table or use prose and a list instead.
Test code and links on the reader’s path
A code block is part of the interface. The reader should be able to copy it, recognize its language, understand the required state, and confirm what a successful result looks like.
Put commands in text and name their language
Do not hide a command in a screenshot. Text can be copied, enlarged, searched, translated, and read by assistive technology, which is why Google’s guide advises against images of code and terminal output.
Use the code fence or HTML class that tells the renderer what language it contains. Put prerequisites and a success signal in nearby text rather than relying on an image caption.
# Run from a disposable test workspace.
python3 check_documentation_accessibility.py rendered-page.html
The expected result is a PASS line that names the file checked. A failure should name the structural issue so the author can repair it without guessing.
Give links a destination readers can choose
A link list is often how people scan a technical page. “Click here” becomes meaningless when it is separated from its paragraph, but “Read the documentation review checklist” tells the reader what they will get.
Name unusual behavior near the link when it changes the next move. A download, external application, same-page jump, or new tab should not be a surprise.
Test visual information has an equivalent text path
An alternative is not a caption copied into an alt attribute. It is the information someone needs when they cannot use the visual presentation.
Write alternatives for the visual’s job
Describe the result or decision the visual supports. If a screenshot proves that a request returned 200, say that, and keep the matching response detail in nearby text.
Open edX’s checklist draws the useful boundary: a meaningful graphic needs equivalent information, and a complex graph or diagram may need adjacent text or a data table. Decorative images should use an empty alternative so they do not add noise.
Check contrast and non-color cues together
A red error state must also say that the request failed. Color can reinforce a label, but it cannot be the only way to understand status, priority, or a comparison.
Use the WCAG 2.2 Quick Reference to inspect the relevant success criteria for text alternatives, information and relationships, contrast, keyboard operation, and link purpose. The standard is a reference point, not a replacement for trying the page’s real task.
Run automated checks before manual documentation testing
Automation can confirm markup patterns. It cannot tell whether focus is easy to find, whether a code sample wraps into unreadable fragments, or whether the page still makes sense at high zoom.
Automate repeatable source failures
I used the checker below on a fixture with one page title, ordered headings, a declared Bash block, descriptive link text, table headers, and an image alternative. The run passed after I restored those contracts.
Documentation accessibility checker on the repaired fixture
<img src="/static/images/articles/documentation-accessibility-checklist/checker-pass.png" alt="MacBook Air terminal window showing python3 check_documentation_accessibility.py rendered-page.html and a passing structural accessibility result">
The checker reports a passed structural check for the repaired fixture. It does not claim to test keyboard operation, color contrast, or screen-reader output.
Run it against generated HTML, not only the source Markdown. The rendered page is where plugins, templates, syntax highlighters, and image components can change the structure you intended.
Test the reader’s route with a keyboard and zoom
Tab through the page from the browser address bar. The current control should stay visible, links and controls should work without a pointer, and the order should match the reading order.
Then zoom until the page reflows and read the page with a screen reader when possible. The documentation review checklist covers the wider release review, including links, metadata, and the rendered frame.
Make accessibility testing a documentation release gate
Put this checklist beside the page template and run the checker in the same preview step that validates links and examples. The documentation style guide template can record the owner, release trigger, and manual-test boundary for rules that change with the product.
Accessibility gets cheaper when it is part of the authoring contract rather than a repair after launch. Start with one task page, preserve the semantics that explain its route, and let the rendered review show what the source alone cannot prove.
Top comments (0)