A11y pal(ly)- crafting universally good docs

Transcript

Sangeetha: Hey, I'm Sangeetha and this is A11y Pally, crafting universally good docs. Before we begin, there is a disclaimer. This is not a deep dive into this large, cavernous, wonderful, musical venue in north of London, where you might go to watch your favorite musicians, with 10,000 of your most sweaty, closest friends.

This is a talk about accessibility and what that means for product design and what that means for documentation and why it's important to invest in accessibility. But since I lured you here under false pretenses, I will give you free fun facts about Alexandra Palace. It was opened in 1873 and closed 16 days afterwards, because of a great, big fire. In it's storied 170 years of existence, it has not only been an incredible concert venue, it has been an art college, a chapel, a hospital during World War I, a refugee camp during World War II, a television studio, home to a rollercoaster and also a ginormous Henry Willis organ, which is probably still there, if you go look for it. It was also the site for Dr Barton's airship in 1888, the site to the first aerial photograph in 1882. And as luck would have it, there was a great big fire again in 1980, but it made it's starry comeback as the victory square in the 1984 film adaptation of George Orwell's "1984". And your third fun fact is that park around Alexandra Palace is biodiverse, so it has 700 species that live amongst the greenery and this is just not on Friday nights.

Now that we've gotten that out of the way, let's talk about accessibility and what that means for documentation. It might be a noble cause to invest in accessibility, but it's also an incredibly selfish one, because it's an investment in your own future, because everyone will be temporarily or permanently impaired at some point in their life, and that's according to the World Health Organization, who are very sprightly people. Some countries like Norway and Spain, legally enforce universal design in both public and private sectors; that's buildings, architecture, transport, ICT, which is computers and technology. And inaccessibility is actually a matter of discrimination.

If you were to go to Oslo, you would see that their staircases are actually highlighted in white so that pedestrians with low vision can tell where the edges of staircases are. New York City, one of the greatest cities in the world, actually one in four subway stations are inaccessible, which makes commuting a nightmare for wheelchair users. University of California, Berkeley, back before the 1970s, students with disabilities were actually housed in Cowell Hospital because that was the only place that they could be accommodated. And if you've ever been to Berkeley, it is just a giant big hill. Students have to plan their classes downhill from each other, because it just was impossible to get to different classes.

In the 1970s, during the Free Speech Movement, there were actually a couple of vigilantes that went and poured cement and made a makeshift ramp. Which later led to curb cuts. But what they noticed from curb cuts was that, not just wheelchair users benefited out of them. We had luggage carriers, wheelchair pushers, heavy cart wielders, skateboarders, and runners, they all rejoiced for curb cuts, because it made their journey just incredibly easier. Which led to the term "curb cut effects". And that's the crossover message, that accessibility's not a zero-sum game. Everybody wins when you invest in accessibility. If national well-being and prosperity and societal harmony is not enough for you, accessibility also reaps economic benefits. Over 15% of the world have a disability. 71% of them leave an inaccessible site immediately, and very recently it's also been a great pot for lawsuits, because there's a lot of money in that. There's been 177% increase in accessibility lawsuits. In the last year, or, the last two years, some of the high profile lawsuits have been Wynn-Dixie, Domino's Pizza, Dunkin' Donuts, Hulu, and the queen herself, by which, of course, I mean Beyonce.

When we talk about disabilities, there is a huge spectrum of disabilities. We have auditory, cognitive, neurological, physical, speech, and visual disabilities. But when we talk about documentation, we talk about a narrow scope of disabilities because it is a very particular interaction that users have with documentation and product interfaces. Particularly, we're more focused on users with low vision, so moderate to severe impairments, color vision deficiency, mostly red-green color blindness, which I think, the statistic is one in 10 men suffer from red-green color blindness. They can't tell the difference between red and green. And on the other end of the spectrum is achromatism, which is no color at all. Users with blindness, who are more likely to use screen readers. Motor disabilities, which usually stem from diseases like ALS, which is Lou Gehrig's disease, Parkinson's, multiple sclerosis.

Those are the core users that we think about when we think about disabilities and docs. But we also talk about temporary disabilities, like changes in device, age, situation, technical infrastructure, and temporary situations, which are not necessarily disabilities, so when you're on a noisy train, or it's rush hour and you're on, oh as I learned today, on the Jubilee line, which you should never get on at 8:30 a.m., and you're always one-handed and you're trying to use a device with the other. And on the rare sunny day in London, that one day where it's too bright to see your screen, we have to plan for those experiences to be nearly as seamless as regular workflows that we plan for.

The common problems that we see in documentation that makes it inaccessible is lack of alternate text or text equivalents. When you have visual content, like an image, or a video, or a GIF, if a user can't depend on visual stimuli, you need to give them alternate text, because it gives them context, or alternatively, if you don't use all text, you can prepend an image with all of this information so that it sets the context nicely. We have color contrasts. As you see, it gets increasingly difficult the worse you set contrast. For our WCAGs 2.0 guidelines, you have, the A guideline is 4.5 as the contrast ratio. And that's based on font size, color, , font type, all of these things. Having every part of your documentation navigable by keyboard, which is actually quite tricky because you don't think about things like, if you have tabs in your documentation. Everything has to be reachable with tabs, your left and right and bottom keys, your enter key. It's always important to check if it can be navigated by keyboard.

And the last of which is state indicators. If this were an error message, you wouldn't be able to tell if it was red or green if you had red-green color blindness. So, the idea is to not rely on just one visual cue. You should have multiple different cues, like an image with alt text that tells you that's an error, or an error text message. You also shouldn't obscure information when you're asking a user to input something. Because most often, like two seconds after you try typing into a field, you forget what they're asking you. It's good practice to always have the label above the field. Right. These are my very bad drawings. And this is the first of the three case studies that I promised you.

A couple of years ago, BBC looked at their iPlayer, the home of all your favorite shows that everybody seems to have watched and can't stop talking about. The interface on the left was what they had initially. And they realized that there were a lot of accessibility problems with them. Mostly, that TV and radio are such broad categories, but that's what's on the top bar. And every other smaller category, like comedy and drama and documentary are bowed further down the page. Anybody who's navigating it by keyboard had to go through everything to get to that. Also, it was very verbose. If you've ever actually used a screen reader, it's incredibly infuriating because it reads out everything. Unless the page is structured minimally and optimized for a user workflow, it's going to read out every single thing on this page. The keyboard behavior was not intuitive, so just pressing right or left, you couldn't tell predictably where the cursor would go. So they took all of that information and all of the insights from their user studies, and they realized that users require three things. They need to be able to search for what they're looking for. They made it easier to scan a page and they added search functionality. Finding content should be easy, so they made it more scannable, pictures are bigger, text is bigger, and they have broader categories that people could go to right on the top, like channels, categories, A to Z, TV guides, so you could format how you wanted to consume this information. And saving favorites, because sometimes you just want to watch an episode of the series that you're following and you don't need to go through everything, so we have a favorites bar right on the top. So that's case study number one.

Case study number two. Trello. If you use any sort of project management tool, like Canva and all of these things, it's essentially the ability to put things into to-do lists, and things that are done and have to be done, and it makes life a lot easier if you can categorize them, add color labels to them, make them pretty, all of that fun stuff. Trello realized that when you have colored labels, it's kind of hard to tell if you don't have color. So, they added a color blind friendly mode and you can turn that on, and if you do, you can add patterns to the edges of your labels so that you can differentiate it even if there's no color. The response to this on Twitter was actually incredibly positive, which if you've ever been on Twitter, is almost a miracle. Yeah.

Case three, case study three of three is everybody's favorite, public radio, NPR. They had recently, what they've done is they've gone and looked at all of their podcasts, and they've transcribed all of them so that there's a text equivalent for all of their podcasts. And then they went and looked at their metrics as all good engineers and designers do, and they realized that their search traffic increased by 6.86%. Their unique visitors increased by 7.23%. There was an increase in inbound links and search visibility, and all of this was because there was a text equivalent of everything. They had increased SEO and keyword visibility. Which is like a surprising upside to accessibility as well. If you add in all text, you also add in an extra addition to your SEO and keyword visibility. They also noticed that visitors who use English as a second language had a better comprehension of podcasts. Visitors who were in sound sensitive environments or noisy environments were able to still consume podcasts. And also as a result, they had a wider reach. They have a bigger market when you're able to, because now they can easily translate their content to other languages. And finally, and the most cool of all of these things, is they were able to enable search on all of their podcasts. You could search text and it would reference a specific section of the audio on a podcast.

So, all of these insights, all of these anecdotes, what does that mean for you? How should that effect how you write and create documentation and products as a whole? The first is meaningful link crumbs. This isn't "Alice in Wonderland". In the real world, if you pick something that says "eat me", it's probably a bad sign. The same applies to creating links. When you create a link, the link text should be meaningful. It shouldn't just be "here", it should be "read this accessibility guide" and this accessibility guide links to the aforementioned accessibility guide. You should respect the semantics, because native HTML tags like image, caption, table, they all come ready baked in with all of this accessibility goodness. Always prefer the native HTML tags over custom ones that you build yourself. Don't bury context. Be up front, summarize your intent.

You should be able to tell users, this is just a good writing tip, except if you're writing fiction, just right up front what you want, briefly summarize what the text is about and this tells the user what they're going to invest time and effort into and if they should. Have multiple cues, don't rely just on one visual cue, like color or geographical location. You should combine signals for more success. Like we saw before, if you have like an error state, have like an error message or an error symbol with alt text. And most importantly, write with empathy. You should approach the experience as a user. You should create personas, you should test edge cases, accessibility's an incredibly human discipline. You should also approach it in an incredibly human way.

Part two of how you should write is you should think about documentation, the architecture and the hierarchy, because that navigation tree tells you what your journey is going to look like. That's very important for screen reader users because they just need to know where to go to get what they need. Always make sure that the way you use headings is consistent because that also helps screen reader users because they don't have the visual context. You should always set rules, like H1 should be top level tags, H2 should be subheadings, and you should have a guide of how you use elements. You should label with context and care. You should label in a way that it is sufficiently descriptive. Sometimes when you write alt text for images, it doesn't sufficiently convey what the image is.

You have to also describe the subtleties that are baked into the image. You should also position it in such a way the context is never obscured. You should also test a common workflow because that's the only way you know how a product works. You should go and replicate the user workflow. Try it without color, try it with a screen reader, try it with just a keyboard. It breeds empathy for the user experience but also tests it from all possible angles.

Advocate for UI improvements. You all are some sort of developer advocate. What you should do is, you see something, you should say something. Be the change you want to see in the world, or something less corny. Yeah. To iterate once again, you should write with empathy. An accessible solution delights when it blends into the product ecosystem, and it provides the user with all that they need but is still personalized to their particular abilities. You should be cognizant of how you create things. You should think outside the box. Accessibility's all about being creative and being surprising and just being human.

It wouldn't be a talk if I didn't give you a list of other resources that you should go and see. So the Internet, between all of the and the cat memes, there's actually pretty useful cool stuff on it. I would highly recommend our style guide. Also Pinterest's best practices is cool. Highly recommend Vox's accessibility guidelines because it's broken down by job title, which is pretty cool; what you should do as a designer as opposed to a front end engineer, back end engineer, writer, all of those things. A lot of love for Rob Dodson's allycasts because it's like a 10 minute deep dive into very particular accessibility problems, especially from the lens of web accessibility. So it has a very great reach.

And finally, you. You go write style guides. I think that's the best way to approach both technical writing and accessibility. Where when you set up a style guide for how you want your documentation to be, it's not only a mission statement where you tell others what you want your documentation to be, but it's also a roadmap to show people how to get there and hold them accountable. Go for it and make all things accessible.