Accessible Inside Out - Practices for Better Code and Documentation

Agenda

  1. Let's talk about accessibility
  2. Meet the developers
  3. Accessible code, documentation and tooling

Let's talk about accessibility

What does (digital) accessibility mean?

So what's disability?

Why is accessibility important?

Meet the Developers

Alex

Vera

Sofia

Accessible code, documentation and tooling

Documentation

Code

Sources: Julia Ferraioli - Writing Accessible Code, Josh W. Comeau - Hands Free Coding

Tooling

Recap

What I hope you remember from this talk

Sources and links

Transcript

[Slide with text "Accessible inside out - Practices for Better Code and Documentation"]

Hi! Let me start with the story. I was working in a project, I was working as a front-end developer there and we had decided to use an external design library, or design system library. I needed to first time check something from the components from that design system library's documentation. Well, I went to the site and I opened the front  page.

There was this huge autoplaying video and it was something like, I think it was a video filmed from drone going up or down or something, but there was, like, unexpected motion there. And you see, I have one type of vestibular disorder, which makes me feel dizzy or sick, or other symptoms if I see some, well, unexpected movement.

I want to emphasize that I'm using a huge screen and that that browser window took the whole space on that screen so that video was really huge. And when it started playing and I saw it, I started instantly feeling nauseous and disoriented and dizzy and I needed to go lie down for a while. I think it was something from 30 to 60 minutes before I could even think about continuing my work. That was not, like, really nice experience.

And that's actually why I am talking here today about these themes, because it's really important think, for example, accessibility of your documentation so that people don't get sick when they use your products or documentation or anything.

So, my name is Eeva-Jonna Panula, I'm from Finland. I work as an accessibility specialist and senior software developer at Oura Health. So yes, the ring company, [pointing at index finger with an Oura ring]. And I also love to share what I've learned so that's why I'm speaking here. I write a blog, and one thing I'm proud of I want to mention is that I'm actually Certified Professional in Web Accessibility. And when I'm not doing something I could say related to my work, I explore the Finnish nature either by foot or by kayak. So, I like to go outdoors.

And today we are talking about how to make your code, documentation and tooling accessible for people with disabilities, but also, not just for them: it actually benefits all. And we are going to meet three developers who benefit from these things that I'm going to present today.

[Change to slide with text "Agenda" and

  1. Let's talk about accessibility
  2. Meet the developers
  3. Accessible code, documentation and tooling]

First of all we are going to talk a bit about accessibility, and then we're going to meet the developers, and then, finally in the third part of this talk, we are going to look into accessible code, documentation and tooling. So, let's get started!

[Change to slide Let's talk about accessibility]

First of all, let's talk about accessibility.

[Change to slide What does (digital) accessibility mean?]

What does it mean? And before diving into any deeper, I want to say that now that I'm talking about accessibility here, I'm actually talking about digital accessibility.

Because there is difference and there are so many things that we could be talking about in the physical world accessibility. It's really important as well, but in this talk we are concentrating on digital accessibility. In Finnish there are actually two words for these. So, digital accessibility, it's "saavutettavuus" and physical accessibility is "esteettömyys". So that's why I, like, often forget that there is even a difference because in Finnish I think about two different things and for me accessibility, it's most about digital accessibility, because, well, what I do for work. But yeah. Accessibility, or digital accessibility, it's [inaudible] its ability to use digital products, despite having any disabilities or impairments. So that's really like a short way of saying that. And there are some concrete examples I want to list here. So, for example having high enough color contrast, so the contrast between the text color and background color are high enough. There are actually some real hard numbers for that, but we're not going to talk about them right now. And then using semantic markup, so if we are talking about the web world, that would be semantic HTML. And there are other, like, semantic markups for like mobile world and everything. But concretely this means that if you have some text, for example, on your website, or product, and there are headings, they are actually annotated as headings there. And, so, that assistive technology will recognize them as headings so it's not just some bold text but it's actually annotated as heading.

And then one concrete good example is having captions for videos. This helps, well, I'm gonna go to the helps part later, but it is essential for people who are deaf or hard of hearing. So, they can't watch the videos without captions.

But it also helps everybody, because uh, you know, when you're traveling in a crowded train, you want to watch a video and that has captions, you can do that without interfering anybody on the train. But if it doesn't have captions, you can't do that.

But to talk about accessibility, we actually need to talk about disabilities as well. So let's talk about disabilities!

[Change to slide "So what's disability?"]

There are different ways to categorize disabilities, and one way to do that is to the following categories. So first, cognitive disabilities. That's actually the biggest group of disabilities out there. And this consists of things like autism, ADHD, mental health issues, brain injuries. And sorry, not in this one, mental health issues don't go under this one in this categorization. Sorry. But other disabilities that affect cognitive functions. Then there are visual - So, blind people, those who have low vision, or color blindness. And then auditory, so, Deaf or Hard of Hearing. Then disabilities that affect mobility or like, motor skills, so being quadriplegic or MS or other things that affect mobility. Then, mental health issues. I wanted to bring this one as a separate one here so, that's why like i said that it's not in this categorization, it's not under the cognitive disabilities.

And then compounded. So, I want to also remind that if a person has some sort of disability it doesn't mean that they can't develop or get another type of disability. Or that they don't have another type of disability. And when person has multiple disabilities, their needs, accessibility needs actually are different from if a person, for example, is Deafblind, then they need different things than deaf or blind people. So that's a good example of these compounded disabilities.

And also, when talking about disability, I really want to emphasize that use the word disability. Don't kind of like dance around the term - just use the word disability. And don't use things like "special needs" or "differently abled" or something like that unless a person with disability specifically asks for that. So, just say disability.

And one other aspect I want to point out from disabilities is that they can be either permanent, temporary or situational. And permanent disabilities such as blindness, so if a person is blind they most likely will be blind for the rest of their lives. But then there are temporary disabilities, so if you break your arm, and then you can't use one of your hands for a while, that's temporary. And then there are situational. So when you go outside on direct sunlight, you can't really see what's going on on your mobile phone if it's not made accessible and used high enough color contrast for example. Or when you are in loud environment and you can't hear, that's also situational.

And there are two things I further want to point out from this. First, even if you have temporary or situational disabilities at some point, you really can't understand the like the experience of those who have permanent disabilities. So always remember to listen to them and and not assume something from your own experience, if you've had situational or temporary disability.

But, however, I want to also point out that even though accessibility is making, for example, digital products accessible for people with permanent disabilities, everybody benefits from that because when we are having some sort of temporary or situational disabilities, those things that have been made those people with permanent disabilities in mind, that also affect affects us as well. So yeah.

[Change to slide "Why is accessibility important?"]

Then quickly about why accessibility actually is  important. So, first of all, I want to say that it's human right.

And we are living in a world where everything is more and more digital every day, and if we create products that are accessible only for people who have have good vision, can hear, have good fine motor skills, and are neurotypical, we are actually excluding lots and lots of people, because well, when we age we are, there are things that we can acquire, or disabilities we can acquire while we age, because it's more likely to have some sort of disability the older you are.

And then there are also things like accidents that might cause disabilities. I actually have brain injury which is caused by falling and hitting my head, so that was a surprise. So it was a good lesson of that there are two types of people: those who are disabled and those who are not yet disabled. So there's that. And there is in the world about 15 % of the population have disability. So, there is lots of people with disabilities as well.

And, connected to today's talk, I want to also emphasize that we, disabled people, have also right to work. And that's why it's really important to think about tooling, and tools we use in our work that they are also accessible.

So there is that. And we all benefit from accessible products, as mentioned in the previous slide. And then there is also money in it because, you know, we, people with disabilities, we spend money as well. And we tell about accessible products to others. And we also tell about inaccessible products to others, so, there is that too.

And another aspect, when it comes to money is that, again, it's really important that people with disabilities can work, and we provide environment where they can work, or we can work, and and think about the accessibility of workplaces as well.

And then there is this law aspect to accessibility. I'm not going to go into that now, but if you are uh interested about it there are different laws in different countries, and you can search for for accessibility laws and then your country name. I bet you find, things about that topic there but I'm not gonna go into that one here. But yeah, so, I hope that from this slide you will remember that it's actually human right, accessibility is human right, and it's right thing to do, and we need to think about our users, colleagues and future colleagues as well.

[Change to slide "The developers". There's an illustration of three developers with their names and positions under each illustration.]

So, all right, let's meet the developers! So, I'm transferring to another theme here.

Here they are: So, Alex. They are back-end developer. Then Vera. She is full-stack developer, and Sofia, who is front-end developer. And let's get to know them a little bit better.

[Change to slide "Alex" with text:

So, first, Alex. As mentioned, they're a backend developer.

They have low vision, so they don't see that well, almost not at all, and, they use, sometimes browser zoom, sometimes they use screen magnifying software, and sometimes they use screen reader. So it's important to think that our code, documentation, tooling goes well with these assistive strategies or technologies.

[Change to slide "Vera" with text:

Then we have Vera. She's, as mentioned, full stack developer who has fibromyalgia and she uses sometimes keyboard for navigation, and sometimes voice commands. And one thing I want to really emphasize here is that she never uses a mouse. She uses either keyboard or voice activation. So this also adds some requirements for the code and documentation, tooling, everything.

[Change to slide "Sofia" with text:

And then Sofia, who's front-end developer. She has ADHD and also vestibular disorder, so the same thing I mentioned I have, so I feel close to Sofia. Also Sofia is front-end developer, so we have lots of things in common. She uses actually reduced motion setting on the computer. So that means that user can turn on this setting to reduce motion, and that reduces motion from from the operating system level and actually websites and apps have a way have ways to respect that setting. So, there is that.

One thing that's really hard for her is understand, if information is all over the place so, there's one piece of information in Google Docs and then one piece of information is in Confluence and then something is as a comment in code. So, it's really hard for her to understand these things. So that's that's one thing I want to emphasize and tell about Sofia here. All right.

So, here are Alex, Vera and Sofia.

[Change to slide "Accessible code, documentation and tooling"]

And now we can actually talk about accessible code, documentation and tooling.

[Change to slide "Documentation"]

Let's first talk about documentation.

When I'm talking about documentation here, I mean both internal documentation so, companies' internal documentation, which can be anywhere. I've been in companies which use, for example Confluence or Google Docs for this, but can be basically anywhere. So wherever information is.

And then, another aspect is actually, documentation of our software or API or something else. So these two things go under the documentation.

And there are two aspects to documentation: there is the platform, so what we are using for the stored information, and then the content itself, so what goes into there. Like, what we document. Let's talk a bit about platform.

[Change to slide "Documentation - Platform"]

So as mentioned I've seen, for internal documentation I've seen Confluence or Google Docs, and other other things used, so that's one thing. And when companies using some third-party tools or libraries for this, we don't have that much say to the accessibility aspects. So, basically, we can file bugs if there are some problems, so that is a problem.

But also, when we are creating documentation for our product or API or whatever, there are libraries that, well, some of the libraries are more accessible than others. So it's really important to pay attention to the accessibility of the tool you are deciding to use for documentation - be it internal or external.

So here are a couple of concrete tips to think about when talking about documentation and especially the platform. So first, well, ensure that the platform is accessible. And this goes especially for the internal tools but also for software documentation, ensure that the library or tool you're using is accessible. So it can be used with different types of assistive technologies and and the information structure is clear, for example.

And if you are building your software documentation yourself, so like from the scratch basically, and not using any ready-made solutions for that, remember to use semantic HTML. Remember to test that it works with keyboard, for example, and follow the best practices for accessible website creation. Because you know you have control in this one if you are building it from from the scratch.

And also, use, like, um, this goes a bit into the content as well, but

but especially, if you are, um, creating the documentation yourself or the, like, the platform yourself, um, make sure that the layout is simple and clear and highlights the most important things. And this is also one thing that's really good to check when you are choosing your tools for documentation. All right.

[Change to slide "Documentation - Content"]

Then, the content. So, with content I basically mean text, pictures, videos, whatever you have there in the documentation.

So, first of all, when writing something use clear language and structure the content. So using, for example, headers and paragraphs and everything. And this helps especially Alex, because when they are using the screen reader, they can navigate using the headings, for example. And it's also like, screen readers read the content in linear way, and it's easier to understand what's going on if there are clear paragraphs and the language is clear and everything.

This goes for Sofia too. As mentioned, she has sometimes problems with understanding information, so, if the layout is clear and the structure is clear and it already tells what's important and what's where, it's so much easier for Sofia to understand what's going on.

Then also about the content, I know that many people use gifs these days, and they usually contain lots of movement, so be mindful, well, when adding those, because they can be really, really distracting for some people.

So, for example, for Sofia, it's really hard for her to read something when there is a gif moving fast somewhere, or some sort of animation going on somewhere near text. So that's why I would say don't use distracting animations, so the distracting is the important thing here.

Also don't use autoplaying videos because when videos start autoplaying, things can happen, like the story I told in the beginning. But also when something is autoplaying you need to find the place in the page and stop the video. And having autoplaying videos, it makes it hard to use the site with screen reader, so Alex has problems 'cos, you know when they are using screen reader, they listen to the content. And if they are listening to the content and then something else starts playing, that really interferes there, and then they need to find the place, and pause the video. And it might be really hard, if there is conflicting sounds going on. And then for Sofia, well, things like I mentioned might happen, like my story in the beginning. And for Vera it can be really annoying when there is something other playing, and then Vera needs to find her way to the controls and then stop the video, and worst case the controls are not working with keyboard and then she can't actually stop it. So that there is, like, this thing as well.

So, when using videos in your documentation be sure that they don't autoplay, they have captions and they also work and can be controlled with keyboard and voice assistance.

And then one important thing, if you are using images in your documentation: Add meaningful alt texts. Because, when Alex is using your site and going on your site and they encounter an image, they have no way of knowing what what is in that image unless you add descriptive alternative text there. So that's also one tip for documentation.

[Change to slide "Code"]

Let's then talk about the code. So, people with different disabilities code as well, so, I think it's really good to think about the practices how to make code more approachable and accessible. And I think these practices I'm gonna tell here, or the tips, they help everybody. So yeah.

The first thing I'm gonna say is to group blocks of code. Some things that go together and are connected with each other, then make it as a block of code. And group them together. And it's like using paragraphs in written text so that's a really good thing to do.

And also define variables close where they are used, so it reduces cognitive load and need to remember things. So that's a really good thing to do. And this helps Alex when they are using screen reader and going through it, it helps to create a better picture of the code and understand, what's connected with what. Just, you know, the new lines that are used to differentiate between blocks of code, help them to understand that okay, this one is one thing and then another thing starts here. And then for Sofia it it makes the information clearer: what's connected with what. So that that's a good thing for her as well. And then for Vera; she doesn't need to remember when the variables have been defined close to where they are used, she doesn't need to travel to other places to find what the variable even was and to remember that. And it helps 'cos, sometimes using keyboard especially, might cause her pain and, sometimes voice activation doesn't work yet that well with coding, so that's why having things close to each other is a good thing for Vera as well.

And then for variables and functions and everything, use recognizable names. Again, this helps to remember what, what's going on there and also none of our developers need to travel back to remember what this was about and also, because if they are recognizable and also descriptive, then they already tell a story and they don't need to go back and check what this variable was about.

And then the last tip is to use names that are actually easy to pronounce. So this is especially important for Alex and Vera, because for Alex when screen reader pronounces the names of the variables or functions or whatever, it's easier to understand what's going on, and because if you just make up names or you're using non-descriptive names like x or c or really short names, screen readers might have problems pronouncing them. But also for Vera when she's using voice activation. She needs to be able to actually pronounce the names when she's writing something with the voice activation.

So yeah that, those were all my tips for code for today.

[Change to slide "Tooling"]

Then let's talk about tooling.

We use different types of tooling for, for example, coding and this can mean anything from code editor or to extensions or anything that's used with the code itself and also libraries that are used with the project or product you are creating.

So first of all, select tools that are accessible. So, check their documentation, or how they work, so that they are actually accessible. This like what checking that it's accessible it depends on that what we are talking about.

So, if it's, for example, library that you are using in your code, then checking that its documentation is actually accessible, and all the developers can access it and read it and use. It's really important thing. But then if there is some sort of, let's say extension that developers need to use when when developing, then checking that that is accessible and it can be used with screen reader, keyboard and everything, it's really important there as well.

And then another tip is to let developers use the tools that they know that work and let them customize. So, for example, people have different preferences on the code editors. And well for some, it's about preference, but for some it means that if they need to use some particular editor that is not accessible, then they can't use them. So it's really important to keep in mind that not everybody can use for example every code editor.

And I want to again emphasize that when you select your tools, make sure that the documentation for using them is accessible, because, okay if everything works as expected, nobody needs to go to see the documentation but usually nothing's so straightforward, so usually documentation is needed.

And final thing, that I want to say about tooling and accessibility is that don't assume that everybody uses a Mac for development. I'm a Mac user myself so it's been pretty easy for me, but I've been in projects where the first developers on that project, they were using Mac and they set up everything to work with Mac. And then came the first developer with either Linux or Windows, and tried to get the development environment up, and it wasn't working, 'cos there were some problems with the tooling and everything,and it took lots of time to make it possible for them to develop that product, because of assumption that everybody uses a Mac.

And actually, many accessibility related software it works better on Windows, and that's why many people with disabilities, who use different kinds of tools, actually use, for example, Windows for everything. And they don't use a Mac so that's why it's really important, when talking about accessibility of tooling, it's really important to remember that it should be possible to develop with, for example, Windows as well. So, that's something that I really hope that you remember from this talk.

[Change to slide "What I hope you remember from this talk" with text:

All right. So, we are coming to the end of the talk, so I'm gonna show you a slide telling what I hope that you remember from this talk. It's possible that you are right now reading that the bullet points here but I'm still gonna say a couple of words about that as well - what I hope that you remember from this talk.

First of all, I hope that you remember that we all have responsibility to think about accessibility and we all can make decisions that make our colleagues' lives easier. And also one thing, that when making decisions about, basically, tooling or documentation platforms or basically anything, think about accessibility. Remember that, not everybody uses the computer or tools or anything the same way as you, and there are different ways of using the computer.

And I also hope that you remember at least one or two of the tips I've shared today - be it about documentation, code or tooling. And as I know that you are watching this as a video, and not a live stream, if you right now don't remember any of the tips I ask you to just go back and check, so that you will remember at least one or two of them. So yeah, all right.

[Change to slide "Sources and links", see the list in Sources and links-section above]

I've also combined a list of sources and links I've used to when I've been preparing for this talk, so be sure to check them out from the slides that are shared. And, so, I'm not going to stay on this slide for a longer time.

[Change to slide "Thank you" with text Twitter: @EevisPanula Website: https://eevis.codes]

I want to say thank you for listening. My name is Eeva-Jonna Panula, and you can find me on Twitter. My handle is EevisPanula, so e e v i s p a n u l a, and my other social media links can be found from my website, which is eevis.codes so e e v i s . c o d e s. And there are links to both Twitter and my website on the slides.

So, thank you!