Screen readers help users who are blind, visually impaired, or have reading disabilities navigate digital content. This article consolidates what a technical writer directly controls to make content work well with screen readers, and cross-references the fuller treatment of each topic where it already exists elsewhere in this guide. It also separates what a writer controls from what's a platform or engineering responsibility, so neither gets mistaken for the other.
What Writers Control
These are content-level decisions you make in every article, regardless of what platform or theme the knowledge base runs on.
Use clear and descriptive headings
Headings provide structure and help screen readers navigate the page. Use a logical heading hierarchy (H1 → H2 → H3) and never skip levels. See the Headings and Titles guide for the full rule and reasoning — this is the same requirement stated there for scanability, and it applies equally to screen reader navigation.
Write meaningful link text
Avoid generic phrases like "Click here" or "Read more." Screen readers can list all links on a page out of context, so link text needs to make sense entirely on its own. See the Links section of the Formatting Standards guide for the full rule.
| Bad | Good |
|---|---|
| Click here to learn more about API documentation. | Learn more about API documentation best practices. |
Provide alt text for images
Screen readers rely on alt text to describe images. See the Alt Text for Images section of the Images, Screenshots, and Video guide for the full rule and examples.
One addition specific to screen reader phrasing: don't start alt text with "Image of..." or "Picture of..." — screen readers already announce that the element is an image, so this phrasing is redundant.
| Avoid | Prefer |
|---|---|
| Image of the settings panel | The settings panel with the Enable Notifications toggle highlighted |
Use accessible tables
Screen readers read tables cell by cell, associating each one with its column header — which only works if headers are marked as headers, not just styled to look like one. See the Table Accessibility section of the Lists and Tables guide (and the Tables section of Formatting Standards) for the full rule on marked header rows and avoiding merged cells.
Don't rely on sensory cues alone
Don't rely on color, shape, or position alone to convey meaning — a screen reader user won't see a green button or a bolded warning. See the Colors and Highlighting section of the Formatting Standards guide for the full rule.
| Bad | Good |
|---|---|
| Click the green button to proceed. | Click Next to proceed. |
If color is essential to conveying something (red for errors, for example), pair it with a text label or icon, never color alone.
Use real list formatting, not manual numbering as plain text
Screen readers announce list items properly (including the total count and position, like "item 2 of 4") only when the content is genuinely structured as a list — not when it merely looks like one.
If your editor is Markdown-based, standard Markdown list syntax (a line starting with 1., 2., 3. or with -/*) is correctly converted into a real, semantic list by the platform's renderer, and does not need to be replaced with hand-written HTML. The actual failure case is typing a plain number or a hyphen as literal paragraph text, without using the editor's list formatting at all — for example, pasting "1) Step one" as a plain paragraph rather than using the numbered-list tool or Markdown syntax. If you're unsure whether your platform's editor is producing a real list versus styled plain text, check the rendered HTML or ask whoever owns the platform.
Video captions and transcripts
Every video needs captions or a transcript. See the Video and GIFs section of the Images, Screenshots, and Video guide for the full requirement.
Reading order matches visual order
When an article uses a visually complex layout — side-by-side content, callouts placed next to (rather than within) the main flow, multi-column comparisons — check that the order a screen reader will announce the content in matches the order a sighted reader would naturally read it in. A layout that looks fine visually can still read out of order to a screen reader if the underlying content order doesn't match the visual arrangement. When your platform's editor gives you a choice, prefer stacking content in a single reading-order-friendly column over complex multi-column visual layouts within an article.
Platform and Engineering Responsibilities
The items below matter for accessibility but are generally implemented at the platform, theme, or template level — not hand-coded by a writer inside an individual article. If your knowledge base platform doesn't already handle these, flag it to whoever owns the platform rather than trying to solve it inside article content, and avoid pasting raw HTML or ARIA attributes directly into article content unless your platform specifically supports and expects that.
- ARIA landmarks and roles (
role="navigation",role="alert", and similar) — used to help screen readers navigate site-wide regions like navigation menus and alert banners. This is a template-level concern for the knowledge base's overall page structure, not something added per article. - Form labeling — every form field needs a properly associated
<label>element, not just a placeholder (placeholders disappear once a user starts typing, and aren't reliably announced by all screen readers). This applies to search bars, feedback forms, and any interactive form embedded in the knowledge base's template — a platform/engineering concern. - PDF export accessibility — if your knowledge base supports exporting articles to PDF, verify the export produces a tagged PDF (with real heading structure, alt text, and reading order preserved) rather than a flat image or untagged text layout. This is a function of the export tooling itself, not something a writer can control article by article, but it's worth confirming with whoever owns that export pipeline, since an inaccessible PDF export can undo everything done correctly in the source article.
- Screen reader testing — periodically test actual published pages with a real screen reader (NVDA, JAWS, VoiceOver) to verify that the platform-level implementation is holding up as intended. This is typically an occasional audit task owned by whoever is responsible for the platform, informed by writer feedback about specific articles that seem to behave oddly.
Self-Audit Checklist
Before publishing, check the article against these questions:
- Do headings follow a logical hierarchy with no skipped levels?
- Is all link text descriptive out of context, with no "click here"?
- Does every image have alt text that avoids "Image of..." / "Picture of..." phrasing?
- Are all tables using marked header rows, not just visually bolded text?
- Is meaning conveyed through text or icons, not color, shape, or position alone?
- Are all lists created using the editor's real list formatting, not plain text that merely looks like a list?
- Does every video have captions or a transcript?
- Does the reading order of any complex layout match its visual order?
- Have any platform-level accessibility gaps (ARIA, forms, PDF export) been flagged to the platform owner rather than worked around inside article content?