Basics of documenting accessibility

Note: This post is older than two years. It may still be totally valid, but things change and technology moves fast. Code based posts may be especially prone to changes...

Number of words: 809.

(Loaded 743 times)

Accessibility is a cross-role responsibility and this also means that documenting it has to be a common task. Cooperation and common grounds makes the teams efforts much more effective and it can mean a big difference when relevant documentation clarifies also the minor important decisions about specifics of accessibility.

I was thinking about where to start with documenting accessibility and how to make it simple and effective and not just a dead letter collecting (digital) dust. I think we must again start early and I also think almost everybody in the product cycle must be involved to make it happen.

If production involves sales they should be aware of accessibility as well. They should know the customers needs on accessibility, the national legislation requiting it and also what other companies can and can not offer. Compliance may be binary – either product has to be compliant or not, but a good salesperson should document beyond that, both internally and to clients. “We will deliver an accessible product” is far below enough. Will this cover WCAG on all levels? Will it be the version 2.0 or 2.1? How will it be documented? Such details must be known to sales persons and they should be in written form. Sometimes clients do not know themselves and our sales department can maybe win a case by helping them.

Most digital productions happens as a projects, or are at least organized as such. So as project managers start with planning for work they should also plan for accessibility. And when they plan, they usually also document. So here we must again document our accessibility requirements and plans to make them work. We can go very low on a micro level and define that definition of done for a task includes coverage of WCAG success criteria testing, we can also add accessibility to product sprints and demos, there is a lot on accessibility that must happen on the project level to make it sure we can deliver an accessible product and to deliver may not be enough. We must also document it and support some micro decisions with documentation.

Designers of all kinds have a crucial impact on accessibility and their wire-frames and deliveries must also document accessibility. Keyboard navigation, element states, screen-reader and other assistive technology interaction specifics that are not obvious, color combinations and their contrasts, typography and it’s impact on accessibility and so on. The more that is documented the better as it can make projects mission easier. And with it implementation of accessibility. Acceptance criteria can also be added by interaction designers, so that developers and testers follow them from start and save time later on.

Developers should be aware of the level of WCAG in question as well. It can make a big difference in some aspects of coding and when acceptance criteria is clear on that it makes their job more effective as well. Sometimes a developer must also make some micro decisions that impact accessibility and those must be documented to prevent problems later on when testing or maybe auditing. A big part of accessibility lies on semantics and programmatic interactions and where it is not strictly standardized it should really be documented. Sometimes different browsers and other technologies demand some tweaks and if they are well documented it is easier for everybody on the end. Even the developers that made them in the first place.

Testers and quality assurance people like to get clear acceptance criteria as they make their work much more effective and as they can measure every aspect of product in a predictable way. Documentation is therefore extremely important for them and when we reach out to accessibility specifics it is even more important, so that they can really test the product and use their time and efforts on testing and not on collecting what to even test. This becomes even more clear when they have to use technology that is maybe not so commonly used as for example screen-readers and other assistive technologies. A well written documentation can really help, especially when dealing with new concepts and tech.

So to conclude this reflection – as with implementing accessibility we should also think about cross-team responsibility to document it. It makes the process much more effective and when documentation supports decisions on high and also low level it may be the optimal scenario for everybody included. Products change all the time, so making sure the documentation follow up on it is of course integral part of it and every role involved in the production should also make the necessary efforts to keep the documentation relevant and useful.

Author: Bogdan Cerovac

I am IAAP certified Web Accessibility Specialist (from 2020) and was Google certified Mobile Web Specialist.

Work as digital agency co-owner web developer and accessibility lead.

Sole entrepreneur behind IDEA-lab Cerovac (Inclusion, Diversity, Equity and Accessibility lab) after work. Check out my Accessibility Services if you want me to help your with digital accessibility.

Also head of the expert council at Institute for Digital Accessibility A11Y.si (in Slovenian).

Living and working in Norway (🇳🇴), originally from Slovenia (🇸🇮), loves exploring the globe (🌐).

Nurturing the web from 1999, this blog from 2019.

More about me and how to contact me: