A11y pal(ly)- crafting universally good docs

Google’s Sangeetha Alagappan talks about making your docs inclusive, what accessibility means in the context of documentation, and common pitfalls you might encounter.


  • Accessible solution delights when it blends into the product ecosystem, and it provides the user with all that they need but is still personalized to their particular abilities.
  • You should be cognizant of how you create things. You should think outside the box.
  • Accessibility is all about being creative and being surprised and just being human.
  • Write style guides.
    • Where when you set up a style guide for how you want your documentation to be,
    • It’s not only a mission statement where you tell others what you want your documentation to be, but it’s also a roadmap to show people how to get there and hold them accountable.
  • Disabilities and docs
    • Low vision
    • Colour vision deficiency
    • Blindness
    • Motor disabilities
  • Common problems
    • Lack of alternate text and or equivalents.
    • Colour contrast
    • Unnavigable by keyboard



  • Let’s talk about accessibility and what that means for documentation. It might be a noble cause to invest in accessibility, but it’s also an incredibly selfish one because it’s an investment in your own future,
  • Because everyone will be temporarily or permanently impaired at some point in their life, and that’s according to the World Health Organization, who are very sprightly people.
  • Accessibility Isn't a zero-sum game.
  • Everybody wins when you invest in accessibility.
  • If national well-being and prosperity and societal harmony is not enough for you, accessibility also reaps economic benefits.
    • Example - Over 15% of the world have a disability. 71% of them leave an inaccessible site immediately, and very recently it’s also been a great pot for lawsuits because there’s a lot of money in that.

Disabilities and docs

  • When we talk about documentation, we talk about a narrow scope of disabilities because it is a very particular interaction that users have with documentation and product interfaces.
  • Users with low vision, so moderate to severe impairments, colour vision deficiency, mostly red-green colour blindness.
  • Users with blindness, who are more likely to use screen readers.
  • But we also talk about temporary disabilities, like changes in the device, age, situation, technical infrastructure, and temporary situations, which are not necessarily disabilities,
    • Noisy train,
    • You’re always one-handed and you’re trying to use a device with the other. And
    • On the rare sunny day in London, that one day where it’s too bright to see your screen.

Common problems

  • What we see in the documentation that makes it inaccessible is the lack of alternate text or text equivalents.
  • If a user can’t depend on visual stimuli, you need to give them an alternate text, because it gives them context
  • Or alternatively, if you don’t use all text, you can prepend an image with all of this information so that it sets the context nicely.
  • Use correct colour contrasts.
  • Having every part of your documentation navigable by keyboard.
    • Everything has to be reachable with tabs.
    • Your left and right and bottom keys, your enter key. It’s always important to check if it can be navigated by the keyboard.
  • State indicators.
    • If this were an error message, you wouldn’t be able to tell if it was red or green if you had red-green colour blindness.
    • So, the idea is to not rely on just one visual cue.
    • You should have multiple different cues, like an image with alt text that tells you that’s an error or an error text message.
    • You also shouldn’t obscure information when you’re asking a user to input something.‌

Case study 1: Bbc iPlayer

  • A couple of years ago, BBC looked at their iPlayer, the home of all your favourite shows that everybody seems to have watched and can’t stop talking about.
  • They realized that there were a lot of accessibility problems with the current interface.
  • Mostly, that TV and radio are such broad categories, but that’s what’s on the top bar.
  • Anybody who’s navigating it by keyboard had to go through everything to get to that.
  • If you’ve ever actually used a screen reader, it’s incredibly infuriating because it reads out everything.
    • Unless the page is structured minimally and optimized for a user workflow, it’s going to read out every single thing on this page.
  • The keyboard behaviour was not intuitive, so just pressing right or left, you couldn’t tell predictably where the cursor would go.
  • So they took all of that information and all of the insights from their user studies, and they realized that users require three things.
    • They need to be able to search for what they’re looking for.
    • They made it easier to scan a page and they added search functionality.
    • Broader categories that people could go to the right on the top, like channels, categories, A to Z, TV guides, so you could format how you wanted to consume this information.
    • Saving favourites.

Case study 2: Trello

  • If you use any sort of project management tool, like Canva and all of these things, it’s essentially the ability to put things into to-do lists.
  • Trello realized that when you have coloured labels, it’s kind of hard to tell if you don’t have colour.
    • They added a colour-blind friendly mode
      • You can add patterns to the edges of your labels so that you can differentiate it even if there’s no colour.
      • The response to this on Twitter was actually incredibly positive, which if you’ve ever been on Twitter, is almost a miracle.

Case study 2: NPR

  • Public radio, NPR.
  • They’ve gone and looked at all of their podcasts, and they’ve transcribed all of them so that there’s a text equivalent for all of their podcasts.
  • And then they went and looked at their metrics as all good engineers and designers do, and they realized that their search traffic increased by 6.86%.
  • Their unique visitors increased by 7.23%.
  • There was an increase in inbound links and search visibility.
  • They had increased SEO and keyword visibility.
  • Visitors who were in sound-sensitive environments or noisy environments were able to still consume podcasts.
  • As a result, they had a wider reach.
    • They have a bigger market when you’re able to because now they can easily translate their content to other languages.
    • They were able to enable search on all of their podcasts.
      • You could search text and it would reference a specific section of the audio on a podcast.

How should you write?

  • How should that affect how you write and create documentation and products as a whole?
  • You should respect the semantics because of native HTML tags like image, caption, table.
  • Always prefer the native HTML tags over custom ones that you build yourself. Don’t bury context.
  • Be upfront, summarize your intent.
  • Have multiple cues, don’t rely just on one visual cue, like colour or geographical location.
  • Most importantly, write with empathy.
    • You should approach the experience as a user.
    • You should create personas.
    • You should test edge cases‌.
Quote “accessibility’s an incredibly human discipline. You should also approach it in an incredibly human way.”

Documentation, the architecture and the hierarchy

  • Navigation tree tells you what your journey is going to look like.
  • That’s very important for screen reader users because they just need to know where to go to get what they need.
  • Always make sure that the way you use headings is consistent because that also helps screen reader users because they don’t have the visual context.
  • You should always set rules like H1 should be top-level tags, H2 should be subheadings, and you should have a guide of how you use elements.
  • You should label with context and care.
  • You should label it in a way that is sufficiently descriptive.
  • Sometimes when you write alt text for images, it doesn’t sufficiently convey what the image is.
  • You should also test a common workflow because that’s the only way you know how a product works.
  • You should go and replicate the user workflow.

Advocate for UI improvements

  • If you see something, you should say something.
  • To iterate once again, you should write with empathy.