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)
Hay Kranen, Emma Dawson, Eric Eggert, AlaaMU, Patrick Sanwikarja, Accessabilly, Matthew Balaam, Wouter de Boer, Haz, Anurag Hazra ⚛, Kilian Valkhof, Jen Gorfine, Ted Barnes, Jackie Daytona AKA Chad Farthaus, Giamma, Sage ⚡️, Weston Thayer, knut (🌉 #structuredconf22), Michael Hastrich, Phil, Kyle Gach, Leonardo Elias, джуниор софтваре енгиниир, Ricardo Velhote, Grunet, Macarena ♡, BH, Alicia Jarvis (She/Her/Elle) 🇨🇦🇺🇦🌻, Kamilouri, Rifat Najmi, Jessica Speigel, Dave Rupert, Valentin Audic, Aaron Gustafson, Henrik Kjersem, Alison Green, This Dot Labs, Brad Frost, nic, 🏳️🌈 ✊🏾 future ghost, sue 🐻, Christian May, Jonathan Dallas, Frank 🇧🇷, juan olvera, Lupis, Gaurav Gupta, Fredrik Sogaard, stvfrnzl, This Miss Molly, Deborah Edwards-Oñoro, AT for Education: ATforED & Access4Employment, Travis Maynard and Zoran Gavric liked this
Eric Eggert, Ioanna Talasli, 𝟶𝚡𝙵𝟶𝟿𝙵𝟾𝟼𝟾𝟽, Giamma, nic, Dave Rupert, Aaron Gustafson, Brad Frost and Luciano Lima reposted this
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:
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:
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:
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.