Documenting Accessibility Decisions

The ability to focus and remember is a privilege, especially for people with disabilities. Which makes documenting accessibility decisions that much more important.

Cartoon image of business man holding a file folder standing in a file cabinet with keyboard and search button nearby
Cartoon image of business man holding a file folder standing in a file cabinet with keyboard and search button nearby

Focus and memory are privileges, perhaps even more so, for people with disabilities, who are:

  • more likely to be at a socioeconomic disadvantage as measured against people without disabilities, which affects their ability to focus. When you are worried where $$ is coming from for expensive medical treatment or whether or not you will be able to keep a job and the health insurance that goes with it, you aren’t going to be able to easily focus on things other than that. Maslow’s hierarchy of needs is definitely at play here.
  • more likely to have medical issues impacting their focus. That can take the form of attention deficit disorder, being on the autism spectrum, having diagnosed (or undiagnosed) hearing loss which creates *perceived* focus issues, having mental health issues from some other life-threatening issue such as cancer or paralysis distracting them from their ability to focus, or having medication side effects impacting the ability to focus or memory retention.

Once we flip the narrative from assuming that people can focus and remember to the opposite, accessibility program documentation decisions become fairly simple. Document every meaningful decision, and assume that no one involved in accessibility has the guaranteed luxury of narrow focus or a strong memory.

“I can’t remember what I recommended for that component, it was 8 months ago!”

“I can’t find the gap analysis from Project Doodah”

“Where is the user research report for those combo boxes?”

If I had a nickel for every time one of these thoughts ran through my mind, my 401K account would be fully funded. And to be completely accessible, internal WCAG UI consistent navigation and identification guidelines must be met. Which means these details are important, and important accessibility decisions and details should be fully documented for future reference.

Here are some of the most important types of accessibility information that should be recorded for posterity.

  1. Test Environments

You are *never* going to be able to test all environments or all permutations of assistive technology. It just isn’t possible and anyone who thinks it is either has a ton of resources without better things to do with them, or really doesn’t understand the problem. It is extremely important that what *was* tested gets recorded. An example of this would include testing information for:

  • Hardware T
  • Version U of operating system V
  • Version W of browser X
  • Version Y of assistive technology Z

2. Results

Past audit results are always useful for future reference — otherwise, it is difficult to figure out whether a bug that was fixed got reintroduced, or whether it was there all along. That is a very important distinction to be able to draw for root cause analysis. A useful level of detail is something like “This is the .CSV file that was uploaded into Git and attached to ticket 2168”.

When associated with all the environment issues above, you should always have the minimum amount of information needed to replicate any accessibility issue.

3. Findings

Findings can come in many different varieties. They can be:

  • User Research findings
  • External audit / compliance findings
  • Anecdotal findings (something like “the new contractors maintaining the database GUI seem to be introducing a higher than average number of accessibility defects.”)

4. Advice and/or coding instructions

Any time you find yourself giving the same advice for a second time, it needs to be documented somewhere. This is especially true for best practices. Some examples include:

  • Make your progress bars decorative and provide the information elsewhere
  • If the alt-text is over 2000 characters use a text file
  • Minimal keyboard behavior that must be supported
  • When and how to use ARIA-live
  • Decisions, like product roadmap was re-prioritized based on user research findings or IE no longer being tested because their usage has dropped below 5 % of the total browser market

Final Advice

Be careful that all of the documentation above complies with your organization’s electronic document retention policy. The litigators will tell you there is a fine line between recording things that are valuable for reuse, and recording things for TOO long where they end up having to be produced in court actions, and end up work against you.

Written by

Accessibility Architect @ VMware. W3C Silver, ITI & IAAP GLC committees. Degrees in CS, law, business. Wheelchair user w/ a deaf daughter.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store