Notes from Write the Docs Toronto: Creating accessible docs

by Nicola Yap in collaboration with Sangeetha Alagappan and Darcy Lima

A to Z of accessibility

Stats: 1 bill+ have a disability, 71% leave an inaccessible site immmediately

Inclusion considers the full range of human diversity: matrix of

  • vision, hearing, speech, mobility, cognition, social and cultural identity
  • situational, temporary, permanent, everyday interactions

Inclusive design is design that considers the full range of human diversity with respect to ability, language, culture, gender, age and other forms of human difference. Inclusive Design Research Centre

Inclusive design benefits everyone (e.g. the curb cut effect).

Case studies

BBC iplayer:

  • searchability
  • favourites
  • usability


  • adding patterns to labels i.e. not just colour


  • transcripts increased traffic
  • improved SEO
  • helping those with hearing impairments but also those whose English is a second language

Writing accessible docs

Checklists can get very long, cumbersome, and often written for UI design instead of tech writing.

So how should I write?

Leverage your tech writer skills

Focus on the user, not the checklist

Focus on clarity and ease of use, will help with learning difficulties or those in situation where it’s difficult to focus/pay attention

  • make docs easy to scan and navigate
    • consistency: language, structure
    • options to turn off nav or sidebars
    • use headers properly
  • label with context and care
    • text description (alt text): write in context, what message trying to get across
    • document alternate ways to access content
    • ensure to add ARIA labels when necessary
  • maintain clear and concise text
    • avoid referring to format e.g. bold
    • avoid references by direction
    • spelling out symbols
  • most language considerations for localization also apply to accessibility
    • avoid jargon
    • avoid local or cultural references

AI is for specific use cases

  • automatic captioning and image recognition can be useful in specific situations when they produce information that is predictable and well understood in context
  • not reliable for providing rich context e.g. screenshots with specific data and UI elements you want to highlight and describe

Test a common workflow

  • get to know the experience of your users
  • test the “core experience” with a representative sample of your docs e.g. screen reader (built into most OS), turn off CSS/JavaScript, contrast on screen
  • document alternate input methods that are specific to your product
  • can go through WCAG or W3C group’s site for ideas on use cases

Redefine success criteria

Empower users with control and choice

  • use Infusion to provide a preferences pane to customize the user experience: changing text size/style, line spacing, contrast, layout and nav, links and buttons, audio and video settings

Empower users with knowledge

  • oen of the Floe resources for learners is the First Discovery Tool. Enables exploring different types of learning preferences
  • BBC My Web My Way site describes how to leverage existing settings on computers and devices to customize the user experience

Get doc accessibility feedback

  • Toronto: attend an IDRC community session and get feedback
  • contact local organizations that support people with disabilities

Author: Cynthia

Technologist, Librarian, Metadata and Technical Services expert, Educator, Mentor, Web Developer, UXer, Accessibility Advocate, Documentarian

Leave a Comment

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: