Documenting Accessibility Decisions
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 about 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 be able to quickly 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 people can focus and remember to the opposite, accessibility program documentation decisions become pretty simple. Document every meaningful decision, and assume that no one involved in accessibility has the guaranteed luxury of narrow focus or strong memory.
“I can’t remember what I recommended for that component; it was eight 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. To be completely accessible, internal WCAG UI consistent navigation and identification guidelines must be met. These details are essential, and essential accessibility decisions and details should be fully documented for future reference.
Here are some of the most essential types of accessibility information that should be recorded for posterity.
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 doesn’t understand the problem. It is essential 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 helpful for future reference; otherwise, it is difficult to figure out whether a fixed bug was reintroduced or was there all along. That is a crucial distinction to draw for root cause analysis. A proper 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 environmental 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 seems to be introducing a higher than average number of accessibility defects.”)
4. Advice and 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, were re-prioritized based on user research findings, or IE was no longer being tested because its usage had dropped below 5 % of the total browser market.
Final Advice
Ensure all 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 have to be produced in court actions and end up working against you.