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.
The expected result is a line that names the file checked.
A failure should name the structural issue so the author can rep