Technical Writing and Documentation 101: Accessibility in Documentation (Screen Reader Support, Alt Text, Color Contrast)

Accessibility in Documentation (Screen Reader Support, Alt Text, Color Contrast)

Accessibility in Documentation: Screen Reader Support, Alt Text, and Color Contrast

A Practical Study Guide for Technical Writers

What This Is

Accessibility in documentation ensures that all users—including those with visual, motor, or cognitive disabilities—can understand and use your content. This matters because: - 15% of the global population has a disability (WHO).
- Screen readers (like JAWS or NVDA) rely on semantic HTML, alt text, and proper heading structure to navigate docs.
- Color contrast affects readability for users with low vision or color blindness.

Real-world example: A developer with low vision uses a screen reader to navigate your cloud service’s API reference. If your alt text says "image1.png" instead of "Diagram: OAuth 2.0 flow with token exchange steps", they miss critical context. Poor color contrast (e.g., light gray text on white) makes your CLI command examples unreadable.

Key Terms & Tools

• Screen readers (JAWS, NVDA, VoiceOver): Software that reads digital text aloud for blind or low-vision users. Test with: NVDA (free) or VoiceOver (macOS/iOS).
• Alt text (alternative text): A brief, descriptive text alternative for images, diagrams, or icons. Format: <img src="flowchart.png" alt="Sequence diagram: User submits payment → API validates card → Bank processes transaction">.
• WCAG (Web Content Accessibility Guidelines): The global standard for digital accessibility (e.g., WCAG 2.1 AA). Key rules: 4.5:1 color contrast, keyboard navigability, semantic HTML.
• Semantic HTML: Using <h1>–<h6>, <nav>, <button> (not <div>) to define document structure. Why? Screen readers use these to create a "table of contents" for navigation.
• ARIA (Accessible Rich Internet Applications): HTML attributes like aria-label or aria-hidden to improve screen reader support. Example: <button aria-label="Close modal">X</button>.
• Color contrast ratio: The difference in luminance between text and background. Tool: WebAIM Contrast Checker. Minimum: 4.5:1 for normal text, 3:1 for large text.
• Docs-as-code tools (Sphinx, Docusaurus, MkDocs): Static site generators that support accessibility plugins (e.g., Sphinx-a11y). Tip: Use Markdown extensions like alt for images.
• OpenAPI/Swagger UI: API docs tools with built-in accessibility features (e.g., keyboard navigation). Check: Does your Swagger UI pass axe DevTools scans?
• DITA (Darwin Information Typing Architecture): XML-based standard for technical docs. Accessibility feature: <alt> tags for images, <shortdesc> for summaries.
• EPUB accessibility: For eBooks, use metadata like accessibilityFeature: "alternativeText" and accessibilityHazard: "none". Tool: Ace by DAISY.
• Keyboard navigation: Users should be able to tab through all interactive elements (links, buttons, form fields). Test: Unplug your mouse and navigate your docs with Tab/Shift+Tab.
• Captions/transcripts: For videos, provide synchronized captions (.vtt files) and full transcripts. Tool: YouTube’s auto-captioning (edit for accuracy).

Step-by-Step: Making Docs Accessible

1. Audit Your Docs for Accessibility

• Action: Run automated tools to catch low-hanging fruit:
• axe DevTools (Chrome extension) for color contrast, ARIA labels, and semantic HTML.
• WAVE Evaluation Tool for alt text, heading structure, and form labels.
• Pa11y (CLI tool) for CI/CD pipelines.
• Example output:
  ❌ Error: Image missing alt text (line 42, <img src="logo.png">) ❌ Warning: Low contrast (3.2:1) for #666666 on #FFFFFF

2. Fix Semantic Structure

• Action: Replace <div> and <span> with semantic HTML:
• Use <h1>–<h6> for headings (no skipping levels, e.g., <h1> → <h3>).
• Use <button> for buttons, <nav> for navigation, <table> for data (not layout).
• Add aria-label to icons (e.g., <span aria-label="Search">?</span>).
• Before/After:
  ```html

Installation

Run npm install

```

3. Write Descriptive Alt Text

• Action: For every image, diagram, or icon:
• Decorative images: Use empty alt text (alt="") to hide from screen readers.
• Informative images: Describe the purpose, not the appearance. Example:
  markdown
![Diagram showing the OAuth 2.0 authorization code flow with steps: 1) User requests auth, 2) Server redirects to login, 3) User grants access, 4) Server returns token.](oauth-flow.png)
• Complex diagrams: Provide a long description in the surrounding text or link to a data table.
• Tool tip: Use Alt Text Tester to practice writing alt text.

4. Ensure Color Contrast Compliance

• Action:
• Use WebAIM’s Contrast Checker to test text/background combos.
• Avoid color-only cues (e.g., "Click the red button"). Add text labels or patterns.
• For graphs/charts, use patterns (e.g., stripes, dots) alongside colors.
• Example:
  ```css / ❌ Bad (3.2:1 contrast) / .warning { color: #ffcc00; background: #ffffff; }

/ ✅ Good (7.1:1 contrast) / .warning { color: #d68910; background: #ffffff; } ```

5. Test with Screen Readers

• Action: Navigate your docs using:
• NVDA (Windows): Free, open-source. Shortcut: Insert+F7 to list all links.
• VoiceOver (macOS): Built-in. Shortcut: Cmd+F5 to enable, Ctrl+Option+U to open rotor.
• Keyboard-only: Tab through all interactive elements (no mouse).
• What to check:
• Are headings read in order?
• Do alt texts make sense out of context?
• Can you complete a task (e.g., "Install the CLI") without a mouse?

6. Add Accessibility Metadata (For EPUB/PDF)

• Action: Include metadata for assistive technologies:
• EPUB: Add to package.opf:
  xml
<meta property="schema:accessibilityFeature">alternativeText</meta>
<meta property="schema:accessibilityHazard">none</meta>
• PDF: Use Adobe Acrobat’s "Accessibility Checker" to add tags, alt text, and language settings.

Common Mistakes

Tech Writing Interview / Portfolio Tips

1. Show, don’t tell: In your portfolio, include a "before/after" example of an inaccessible doc you fixed (e.g., a Markdown file with alt text and semantic HTML). Example:
   ```markdown
   

Click here to learn more.

Learn more about our data validation process.
```

1. Talk about testing: Hiring managers love candidates who test their work. Mention:
2. Running docs through axe DevTools.
3. Testing with NVDA/VoiceOver.

4. Using Pa11y in CI/CD pipelines.

5. Explain trade-offs: Be ready to discuss:

6. "How would you balance accessibility with design constraints?" → Prioritize WCAG compliance, then work with designers on alternatives (e.g., patterns instead of color).

7. "How do you write alt text for a complex diagram?" → Provide a short alt text + link to a long description or data table.

8. Highlight collaboration: Accessibility isn’t just a writer’s job. Mention:

9. Working with engineers to add aria-label to UI components.
10. Partnering with designers to fix color contrast.
11. Advocating for accessibility in sprint planning.

Quick Check Questions

1. Scenario: A developer adds a new "Quick Start" diagram to your docs but forgets alt text. The PR is approved without review. How do you prevent this in the future?
2. Answer: Add an accessibility checklist to your PR template (e.g., "✅ All images have alt text") and set up automated tools like Pa11y in CI/CD to block merges with accessibility errors.

3. Why? Automated checks catch issues early, and checklists remind contributors of requirements.

4. Scenario: A user reports that your API reference’s "Try It Out" button in Swagger UI isn’t keyboard-accessible. What’s the likely cause, and how do you fix it?

5. Answer: The button is likely a <div> styled to look like a button. Replace it with a <button> element or add role="button" and tabindex="0".

6. Why? Native <button> elements are keyboard-accessible by default; <div> elements are not.

7. Scenario: Your team wants to use a light gray (#CCCCCC) for code examples on a white background. Is this accessible? How would you adjust it?

8. Answer: No—#CCCCCC on white has a 1.6:1 contrast ratio (WCAG requires 4.5:1). Use a darker gray (#555555 or higher) or add a subtle background color (e.g., #f5f5f5).
9. Why? Low contrast strains users with low vision or color blindness.

Last-Minute Cram Sheet

1. Alt text: Describe the purpose, not the appearance. ⚠️ Avoid "image of" or "screenshot of."
2. Color contrast: 4.5:1 for normal text, 3:1 for large text. Test with WebAIM.
3. Semantic HTML: Use <h1>–<h6>, <button>, <nav>. Avoid <div> for interactive elements.
4. Screen reader testing: Use NVDA (Windows) or VoiceOver (macOS). Navigate with Tab/Shift+Tab.
5. ARIA: Only use if native HTML can’t solve the problem (e.g., aria-label for icon buttons).
6. Decorative images: Use alt="" to hide from screen readers.
7. Complex diagrams: Provide a short alt text + link to a long description or data table.
8. Keyboard navigation: All interactive elements must be reachable via Tab.
9. WCAG 2.1 AA: The gold standard for accessibility (includes contrast, keyboard nav, alt text).
10. Docs-as-code tools: Use accessibility plugins (e.g., Sphinx-a11y) and Markdown extensions for alt text.