A11y-Friendly Documentation

Carolyn Stransky

Videos showed during my presentation (in order of appearance):
📹 Screen reader reading my GraphQL project
📹 Keyboard navigation in Shopify docs
📹 Focus indicators on the UK Government website
📹 Unstyled view of 2018 Twilio docs
📹 Skip links in MDN docs
📹 Alt text on Is There Uber In? search image
📹 How the WAVE extension works in Slack docs

Last given at Open Source 101 on May 12, 2020.


📖 Quick tip: a11y and a brief numeronyms primer
The A11y Project explains what the heck "a11y" actually is.

📚 Accessibility For Everyone
An excellent book from Laura Kalbag that covers everything from what it's like to use the web with a disability to a11y testing your websites.

📖 Assistive technology report
According to the World Health Organization, over one billion people globally need an assistive device.

📖 Myth: Accessibility is 'blind people'
Dave Rupert describes the four categories of accessibility.

📖 The Business Case for Digital Accessibility
The W3 outlines the unexpected business perks of building accessible websites.

📖 A Vision of Coding, Without Opening Your Eyes
Florian Beijers, who has been blind since birth, talks about how he learned to code and the challenges he faced.

📖 Planning for Accessibility
While this article is also by Laura Kalbag, it includes a quote from Anne Gibson that perfectly explains why you should care about building accessible websites even if you're not the one writing the code.

📖 Hack on MDN: Better accessibility for MDN web docs
In September 2018, MDN hosted an a11y hackathon for their web docs and this blog post by Janet Swisher talks about the outcomes of that weekend.

📖 This is for everyone - Government design principles
The design principles enforced by the UK Government, with the link skipping directly to number 6.

📋 2019 StackOverflow Developer Survey
Under Disability Status > Physical Differences, there's a question that asks whether participants are blind or have difficulty seeing. 1.5% said yes.


🛠 Color Oracle
Desktop app that allows you to quickly grayscale your screen or check it from the perspective of various types of colorblindness.

🛠 WebAIM Color Contrast Checker
By putting in the hex of your background color, foreground color and font-weight, you can see if your text will be compliant with accessibility standards.

🛠 Hemingway Editor
A web app (and linter) that highlights problematic words/sentences and offers suggestions. You want to aim for a Grade 8 reading level or lower.

🛠 WCAG - Web Content Accessibility Guidelines
Internationally recognized, adopted standards produced by the W3C to help us build a more accessible web.

🛠 Firefox Accessibility Inspector
Additional developer tools with features like an accessibility picker and highlighting of UI items.

🛠 axe
An open-source rules library for a11y testing.

🛠 WAVE Browser Extension
An evaluation tool that provides visual feedback about the accessibility of your web content by injecting icons and indicators into your page.

🛠 The A11y Project's Web Accessibility Checklist
A thorough checklist that you can use, reference and adapt for your own project.

Assistive technologies

🤖 Apple's VoiceOver
🤖 Microsoft's Narrator
👤 Dwell Control

Code examples

🗝 HTML - HyperText Markup Language
🗝 ARIA - Accessible Rich Internet Applications

Documentation examples

For keyboard navigation, focus indicators and skip links:
🛍 Shopify's Developer Portal
🇬🇧 Gov.UK
🦖 MDN Web Docs
☎️ Twilio

📊 Trello

Public documentation accessibility policy:
☕️ Oracle

Mentioned talks

🎤 Sergei Kriger at ID24
Detailed information about building accessible SVG charts.

🎤 Ashley Bischoff at Fronteers
Straightforward techniques and approaches to plain language in documentation.

Special thanks to

Sara Vieira
She let me use a couple of her websites as the "bad" examples during the talk.

Like my work?

Let me send updates to your inbox (and one day, a newsletter).

Unsubscribe anytime. No spam 🤖

Design and Gatsby starter by Marguerite Roth