a11y-friendly documentation


A talk focused on assistive technology and how to build accessible documentation.

🖥 Current deck from DACHFest 2018
🎥 Recording





degree to which an environment is usable by as many people as possible

web accessibility

degree to which a website is usable by as many people as possible

Laura Kalbag, Accessibility For Everyone

how people interact with the web

assistive technology

screen readers

  • JAWS - job access with speech
  • apple's voiceover
  • microsoft's narrator

keyboard navigation

  • specialist
  • custom
  • on-screen

navigation hardware

  • touchscreens
  • mouth sticks
  • foot-operated mice

switch inputs

  • mechanical buttons
  • foot plates
  • electronic sensors


  • eye
  • head
  • dwell control

accessibility can be intimidating

"Accessibility is often viewed as making your site work on screen readers. In reality, web accessibility is a subset of UX focused on making your website usable by the widest range of people possible, including those who have disabilities."

Dave Rupert, The A11y Project

  • visual
  • auditory
  • motor
  • cognitive

Dave Rupert, The A11y Project

there's a business case for a11y

The Business Case for Digital Accessibility, W3C

but documentation is left out

"documentation is for developers"

One out of every 200 software developers is blind or hard of sight

StackOverflow Developer Survey

"The tutorials are undoubtedly good, but were completely unreadable for me"

Florian Beijers, freeCodeCamp

most of us are already doing it

  • logical layouts
  • user journeys
  • localization
  • cross-browser testing

this is our responsibility

"We may or may not be responsible for writing the HTML, but if the developers we're working with don't produce semantic structure, then they're not actually representing the structures that we're building in our designs"

Anne Gibson, independent consultant

structure and hierarchy

html - hypertext markup language

Laura Kalbag, Accessibility For Everyone

  • h1
  • nav
  • aside
  • ul / ol

aria - accessible rich internet applications

aria roles

<span role=“status">
  Your changes were automatically saved.

MDN web docs on WAI-ARIA basics

aria properties

<div id=“newsletter”>Newsletter</div>
    <div id=“email”>Email</div>
    <input type=“text” aria-labelledby=“newsletter email”/>

MDN web docs on WAI-ARIA basics

aria states

<span aria-hidden=“true”>
  There was an error. Please try again.

MDN web docs on WAI-ARIA basics

best for <div> and <span> elements

focus indicators

  • links
  • form fields
  • widgets
  • buttons
  • menu items
  • can I tab through the page without getting lost?
  • do all focusable elements have focus states?
  • can I operate tabs, accordions, search results, etc with just my keyboard?
  • do I have a skip navigation link?

skip links


alt tags


<img alt=“” src=“globe.svg”>

charts and infographics

  • what are the highlights and lowlights of the graphic?
  • what are the most important and notable parts?
Pie chart with blue, green, pink and yellow sectionsSame pie chart but in grayscale. Many colors now look the same.

code snippets

if (x == true) {
  console.log('Hello world!')

example if-block in JavaScript

if left paren x equals equals true right paren left brace console dot log left paren quote hello world exclaim quote right paren right brace

the example if-statement read by a screen reader

  • <code>
  • use meaningful variable names
  • watch for extra spaces

inclusive writing

This approach will work for our specific use case, but we haven't achieved the objective of truly encapsulating the behavior in a reusable way.

Now every time we want the <tool> position for a different use case, we have to create a new component (i.e. essentially another <tool>) that renders something specifically for that use case.

plain language

"No one has ever complained that something was too easy to read"

Ashley Bischoff, copy editor at The Paciello Group

Ashley's talk at Fronteers

testing for accessibility

wcag - web content accessibility guidelines

most assisitive technologies are free or inexpensive

dev tools

  • firefox
  • chrome
  • safari

free extensions and validators

make accessibility a priority

create an accessibility policy

update your development checklists

browse the web from a different perspective

final thoughts

documentation is for everyone

Thanks for viewing!

The PDF version of the original slides (with all images and videos) are available on SpeakerDeck.

My Twitter handle is @carolstran if you have any questions 💖