Accessibility from different perspectives

I worked in web accessibility in different setups: as a freelance developer specialised in accessibility, as a WCAG auditor and as a full time team member of the W3C's Web Accessibility Initiative. As a developer I would receive audit reports, as an auditor I would write them and as a WAI team member I would work on promoting and documenting the standards these audits are based on. An observation: in the developer role, advocating for accessibility can be the hardest in various ways.

Perspectives

Writing audit reports, a company would request in-depth feedback with the intent to fix stuff (ideally; sometimes it's just because the law says they have to 🤷). At WAI, I engaged with accessibility standards and practices on more of a meta level. When developing tools or resources, I never had to explain why I wanted videos to be captioned or have a visible focus indicator on the stuff we published, because everyone else on the team had worked with WCAG for years, often decades, and many had lived experienced to draw from.

In the developer role, I had more responsibilities than ensuring accessibility, I also had to make sure our assets didn't break under an updated Content-Security-Policy, fix a deployment pipeline or figure out with which templating language my client could use their design system most widely. And then there was accessibility, my main interest and priority. I mean, why have a web app if it's inaccessible… I would often do that work under the radar, sometimes because other developers in the team weren't interested or skilled in that particular area, sometimes because I felt it would take more time to get extra time for a thing than to just do the thing.

Accessibility and support

Accessibility is hard to do bottom up, I found. In some cases, especially when working for government and non profits, accessibility would explicitly be in the requirements and or I would specifically be hired for that expertise. This was great and gave something to work with. In other situations, it was much more of a challenge. Time would go into making a business case (I learned about WAI's business case page late), trying to get budget for external audits or screenreader licenses (procuring JAWS is no fun) and figuring out how to go about recruiting users with disabilities for user tests. And that's still the meta stuff.

When it comes to writing code as an accessibility specialised developer, you can ensure you follow lots of users with disabilities and accessibility specialists to try and learn about implementation issues early. You can find lots of good resources. My favourite are blog posts by developers and accessibility specialists who have tested a solution with users and go at length to describe all the ifs and buts you need to understand the nuance and compromise. But let's be honest, if you want to rely on the official documentation (normative or not) that is also used by browsers and assistive technologies, it can be pretty difficult to find out exactly what to do.

Gaps in documentation

There are systematic problems in accessibility standards documentation:

  • outdated examples are often not marked as outdated and hardly ever removed
  • it is not always clear if examples are ready to use or merely displays of how stuff ‘should work’ if all browsers and assistive technologies followed the standards (a problem ARIA Authoring Practices Guide has)
  • it's hard to find user-tested examples
  • the guidance can be scattered across many places

From the standards org perspective this is all explainable. There is a lot of work on few plates, the consensus process and organisational structure have, besides benefits, an impact on how responsibilities can be and are distributed. It's understandable, but has an effect. It impacts how effectively developers (and designers, content editors etc) can build accessible products. Even if from the standards side of things, you can only do so much to try and have standards that are implemented interoperably by browsers and assistive technology makers. There are relatively few people in the space who specialise in this.

Channeling one's inner developer

From the auditor's perspective, as well as from the standards org perspective, accessibility looks different. The system is, sadly, ableist and almost every website you look at has accessibility conformance and usability issues… it has often frustrated me and made me more cynical than I want to be. You write down the same issues over and over, knowing they are just a few lines of code. I always had to channel my inner developer again, and remember what it can be like. Yes, removing the line outline: none is trivial, and it's extremely ableist to keep it in, but what can a developer do if the QA and/or design departments flag it as a bug and they're the only one on the team who ‘gets’ this need. Let's not blame the developer, let's blame the ableist system we all operate in. Or, as Adrian Roselli recently said, ‘arm developers’ with useful feedback so that they are more enpowered to make the changes (being an auditor often puts one in this somewhat rewarding position).

I don't know where I'm going with this, but thinking about what I'd like to see for the web if I had a magic wand, I would want to see better accessibility documentation (clear, up to date and user tested), more engineering budget for compatibility between standards, browsers and assistive technologies and have legal requirements that make it so that serious organisations see accessibility like they see security and data protection. At least some if not all of these wishes are in progress, of course, in various places… they have been for years, I just wish ✨ change ✨ could be sooner.

Developer experience and user experience

Some say ‘user experience is more important than developer experience’, and I'm all for that sentiment. Of course. Web accessibility is all about users with disabilities. That's the point of it. Developers ‘just’ need to do the job.

But companies who make products they want developers to use effectively, like browsers, have dedicated developer experience teams to try and ensure that developers can use their stuff well. To try and set them up for success. In their case, that makes good business. Might we, as the accessibility field, also benefit from better developer experience (of web accessibility) to get to more widely spread user experience?

What if standards orgs hired content designers, like governments with similarly complex content do so successfully? Isn't explaining standards essential when making standards? In the majority of cases, an inaccessible pattern can be addressed in code, by developers. Might some focus on developer experience be a sensible means to an end? If it was less frustrating to find out how to build, say, a combobox, in practice not in theory, we would more easily get to the end goal: less frustrating experiences to end users.

Besides a focus on quality of documentation, I feel like we should keep the individual developer's perspective in mind, acknowledging they may have constraints beyond their control. We could contribute to fight those constraints by providing executives and team leads with the right tools too. We've got to set teams up for success. That way we all win.

Comments, likes & shares (77)

Great article on how Hidde’s thinking on accessibility has evolved as he’s had different roles. I strongly agree with the conclusion, it’s exactly why Polypane doesn’t just tell you whats wrong but also tells you (in a single way) how to fix it.
For the same reasons as @hdv mentions, we decided to shift our focus to developers for the appt.org platform we’re building. I also believe that you can reach better accessibility most efficiently by ’arming’ developers with great documentation and helpful tools.
“…if I had a 🪄, I would want to see better #a11y documentation (clear, up to date and user tested), more engineering budget for compat between standards, browsers and ATs and have legal reqs that make it so that serious orgs see a11y like they see security and data protection.”
“Might we, as a field, benefit from better developer experience (of web accessibility) to get to more widely spread user experience?” (Nods head in agreement)
A thoughtful piece that resonated with me!
"Accessibility from different perspectives" by Hidde de Vries @hdv hidde.blog/a11y-perspecti…
This is true for a11y and so much more. If you work to make the path to a great UX the most straightforward one, it’s crazy how much you can scale the impact of design. It’s hard and you won’t get the credit, but honestly who cares if it makes everyone’s life better. 1/3
Yes, I wish we all had that magic wand Hidde mentions. #a11y #accessibility
Accessibility from Different Perspectives, by @hdv: hidde.blog/a11y-perspecti…
"Besides a focus on quality of documentation, I feel like we should keep the individual developer's perspective in mind, acknowledging they may have constraints beyond their control." hidde.blog/a11y-perspecti…
"in the developer role, advocating for accessibility can be the hardest in various ways" (src: @hdv's hidde.blog/a11y-perspecti…). Can totally agree. Even with stakeholder support everybody on the team has to cooperate or it is a constant fight. Thread...
Hidde de Vries (@hdv@front-end.social) is a web enthusiast and accessibility specialist from Rotterdam (The Netherlands). He currently works on web standards for the Dutch government and is a participant in the Open UI Community Group. Previously, he worked for W3C (WAI), Mozilla, the Dutch government and others as a freelancer. Hidde is also a public speaker, he has given 73 talks, most recently in Virtual. In his free time, he works on a coffee table book covering the video conferencing apps of our decade. Buy me a coffee Follow on Mastodon Follow on LinkedIn wrote on 1 July 2022:

In two recent conference talks, I learned about making better documentation. First, I heard Adrienne Tacke focus on the documentation's content, explaining how to make it more usable and effective. Then I saw Rich Harris go into how to build a documentation environment, showing a way to approach documentation of projects with a server-side components.

Both talks resonated with me. Good documentation is the backbone of every software project (and also crucial elsewhere, including for web standards like WCAG). For software companies there are countless business reasons to invest in documentation, and for anyone else, yes, improving documentation is still rewarding in many ways.

Types of documentation

To clarify what we're talking about here, Daniele Procida's Diátaxis framework for technical documentation, which I found out about in Rich's talk, identifies four types of documentation:

  • tutorials, to teach people how to use the thing in the first place
  • how-to guides, to teach an experienced user how to do specific things with your tool
  • explanation, to give a high level overview of concepts in your tool
  • reference documentation, to provide matter-of-fact information about functions, APIs etc, to be consulted not read; can be automatically generated

Adrienne's and Rich's talks focused mostly on the first two: tutorials and how-tos.

Be concise and valuable

In her talk, Documentation: the missing pieces, Adrienne went into some very common problems in documentation. She showed how documentation can be unclear and unhelpful, and then went on to show how to be concise and valuable instead. The whole talk is a must watch, but here are some highlights:

  • be more explicit, by expanding acronyms (they can depend on context and not all acronyms are familiar to everyone) and by using the German naming convention (if you can be more explicit in a variable name, do it)
  • be aware of the steps in what you are teaching and avoid skipping steps at all times; this is another moment of stepping (no pun intended) into the shoes of the reader of your documentation, they don't know your project as well as you do, so you want to be explicit and list all gotchas
  • avoid surprises, always tell readers what they will need to make their way through the tutorial (prerequisities, dependencies, paid plans, time)
  • focus on the thing you want folks to learn and help abstract the unrelated setup and configuration stuff away, by creating a starter app, Docker container or sandboxed environment, anything that isn't core to the thing you're currently teaching, but still needs to exist in order for the reader to get started

Interactive tutorials with a server-side component

In his recent JS Nation talk (start at 40s to avoid the crypto advertisement edited into the video ????), Rich explained tutorials are essential, as they actually show users what to do, but they are often overlooked. He showed Learn Knockout, a very early example of a tutorial he loved, and which the Svelte Tutorial was later inspired by, and others, like Lit tutorial, that follow the same model.

For the documentation of Svelte and SvelteKit, the frameworks he created, Rich used four principles:

  • create a sandboxed environment, so that it is safe to make mistakes
  • help muscle memory by disabling copy/paste (controversial!)
  • provide a way to get straight to the solution if you're stuck (Rich calls this “panic button”)
  • meet users where they are (in Svelte/SvelteKit's case: the browser)

Sandboxes for “full stack” projects need both a client and a server component. Some services provide a way to access a virtual server from a sandbox (like CodeSandbox Containers), but they have authentication barriers, to avoid abuse (like bitcoin mining) and can come with some latency, Rich explained. Then he found that on Stackblitz, the server is, rather impressively, ran inside the browser by compiling Node to WebAssembly and running that inside the browser's security sandbox (this is called WebContainers). And that wasn't enough: as he found a StackBlitz environment is made for coding, not learning, Rich teamed up with the StackBlitz team to have some kind of headless version of StackBlitz in order to create what's now in beta as learn.svelte.dev.

Summing up

While these talks were about different aspects of documentation, the speakers were equally determined to ensure that users of their documentation would actually learn the thing easily. It's not easy, neither when creating the content, nor in technically setting up the environment, but it can clearly make a difference.

Digitale toegankelijkheid vanuit verschillende perspectieven hidde.blog/a11y-perspecti… #Digitoegankelijkheid #Toegankelijkheid #a11y