Building accessible documentation sites

Speaker 1 [00:06]

Thank you very much for my very last minute chair. My name is Tania Laird, and today we're going to be talking about what people who write people documentation or build technical documentation sites can do to make this better for people with disabilities. When I talk about accessibility, I talk about better serving our disabled readers, our disabled developers are disabled community members, and of course, if we make things and tools better for people with disabilities, it will just benefit everyone. I'm Tania Lard, I'm the co-director of Quansight Labs, I also sit on the board of the Python Software Foundation, and also the Council of PyLadies, and I just do a lot of stuff. So I work across a lot of different projects, a lot of different topics. So in 30 minutes, I'm going to try and cover just a brief introduction to web accessibility for everyone here so that we all know what we're talking about, what some of the terms that I'm going to be using refer to, then how you can actually take some of these principles as a documentation writer, as a technical writer, and then just some final tips on how you can start with today. There is a lot, a lot when it comes to web accessibility. It's a very, very big topic, there are a lot of technical and social things to think about, so I only have 30 minutes. I'm not going to cover every single accessibility issue ever encountered or every possible solution or every single thing that you can do to meet any compliance requirements. I am actually not going to give you any legal advice on how to not get sued because your tools are inaccessible. Also, I'm going to focus mostly on the authoring side of things, what you as an author can can take on and be responsible for it, because there is also a lot of things that us as developers can take on for it. So why documentation? Why am I giving this talk? A lot of people care about it. I care about documentation, I care about accessibility, so I just want you to reflect how often do you read documentation. A tool. A set of tools. A package. Personally, this is something I do every day. I have a terrible memory, so I cannot for my life remember a syntax. I work with a lot of different tools and technologies, so I visit documentation sites every single A lot of people care about this. Most of our content nowadays is digital, and as digital spaces, we need to ensure that everyone has access to digital and physical spaces. Accessibility should really become everyone's responsibility. Whatever you're building, we should try the same way that we try and be inclusive to other developers and welcoming them and contributors, we also should think about how accessible our tools are. Okay. So let's start with just like some definitions so that we all know, like I said, what I'm going to be talking about. Disability is really an evolving concept, and there are different ways, different variants as you can see through it, like the health model or the social model, but really disability that of someone not being able to participate or being actively excluded from a space or an environment, it's really because disability happens at the point of interaction between a person and society or technology. An impairment, whether it is motor or auditory or visual itself, is not a reason for exclusion. The exclusion comes as a result of having mismatched interactions between a user or an individual and environment and tools they are trying to interact with. So as developers, technical writers, data scientists, we have a huge, huge power to remove these barriers in the same way that we have a huge power to put up new barriers that exclude folks from participating. So in that case, I usually like to think about disability and exclusion therefore not being just inherently or a given because of someone's personal health condition, but actually because of how we are building tools or how we are failing to build tools. Now again, disability, there are many, many, many different types of disability, it can range from visual to auditory, motor or cognitive, and that can really impact the level of access or interactions an individual can have. But also disabilities can be permanent or temporary or situational. So there are situations in which an individual will have an impairment for life. For example, if we're talking about motorists, someone that is missing an arm for whatever reason or if you go skating with your friends, fall and break an arm, that is also temporary disability. And it could also be situational, say you're carrying a baby, or your dog, or something else, right? So every one of us at a given point in our lives are going to experience a disability, whether it is permanent, temporary, or situational. So that's why we should really centre on opening these doors, like removing barriers for people with disability because everyone gets benefit from it in the end. Also something that you're going to hear a lot when we talk about disability is assistive tech. And this is just a very, very big umbrella term that we use in our community to refer to devices that support people with disabilities. Probably some of you have heard about screen readers, it's one of the most popular type of devices, but also all of us that wear glasses on a daily basis, that is just a piece of hardware, a piece of assistive tech. So anything that allows us to interact directly or as a proxy with assistive tech. Now there are guidelines, especially when it comes to web content and when it comes to putting things in digital spaces that can help us bridge the gap and make our tools more usable and more accessible. The most, well, a set of guidelines that we very, very commonly use and are the basis for many of these compliance and conformance regulations that you're going to encounter is the Web Content Accessibility Guidelines. There are also, as I said, some different variants on legal compliance that people are going to have to meet that changes from country to country, continent to continent, but ultimately the WCAG standards is what we have as a baseline. There are other complementary guidelines that tackle specific situations like content authoring. For people that are specifically trying to generate content for the web, or people that are building tools for people to write content on the web. Other complementary guidelines that tackle specifically cognitive disabilities. There are four main principles that form this web accessibility content guidelines. Generally, we are based on four principles that are perceivable, operable, understandable and robust. I understand this is quite a lot, and there is a lot of jargon, and in the spirit of making this more inclusive and easier to follow, let's just use plain language. So the first principle that I'm going to introduce first is perceivable. We interact with the web and our environment through our senses. Whether it is sight or a hearing or a touch or a smell or something, that is how we interact with everything that surrounds us. So this principle of perceivable is basically making sure that individuals can access all the content, I'm centring this now in documentation, that they can access all the content in your documentation site through their senses, at least one of their senses. The second principle is operable. This means that your users or your readers need to be able to move around and use everything on your documentation side. Understandable. We need explicit and clear context for everything in your documentation side. This includes content, why the content is there, why is it relevant, and navigation. It's also close together with operation, like how people move and interact with your documentation site. And finally, robust. This means that your site or whatever thing you're building must be compatible with as many or a wide variety of both users and technologies. So if we think about in terms of technological tools, there is this big umbrella of assistive tech, so folks should be able to use assistive technologies with whatever you're building, that includes compatibility with browsers, that also include accessibility settings that people usually overwrite on their computers and things of the such. So to a certain level, you need to make sure that your tool or whatever you're building is not preventing other tools from interacting with it, but also to give your user enough flexibility to make their own choices. And this is a lot. So how does this actually look for you if you're writing your documentation site? I'm going to be using as an example a project that probably some of you have seen, and it's a PyData Sphinx theme. If you have gone and read Pandas documentation or Scikit-learn or a non-PyMap.libscipy, basically a lot of the projects in the PyData system, more than likely this is a theme that you've you've seen around. Also, it is a project that I maintain and I've been doing a lot of work on, mostly on accessibility and usability, so it gives me some good examples. So let's imagine that you're writing your documentation using this theme, and you want to share it with a blind person or someone with a permanent or temporary visual impairment, Whatever it is. More than likely, if you are a fully abled individual, sorry, this is what you're going to see. This is how you're going to experience a documentation built with the PyData Sphinx theme, like colours, like good layouts, grids, you can see the links and whatnot. But the experience for people with disabilities can be very, very different from VRS. I'm not going to cover every single case of disability because there is too much. But imagine you have a reader with a chromatomaly, this is kind of the experience they would have. They start losing already quite a good amount of information. If you have a reader with chromatopsia, this is going to be what they're going to perceive when you share your documentation site. It's not the resolution on my screen. That is how you're going to experience when you first share that site with them. So a lot of the visual cues that probably some of us or, like, some fully-abled readers use to navigate and interact with your website and your documentation site are just going to be lost. So how do these people interact with your website? Mostly through these assistive tech devices or tools. And there are certain components in websites and your documentation site that then become essential for them to be able to interact with your sites. Some of this are going to be the headings. All those titles that you create, sections of sections, those are essential for navigation, structuring content. Second, landmarks. You can think of the main sections of your website, like the navigation bar, the side bars, the main content, the footer, all of those are landmarks. It serves like physical landmarks that help you orient yourself in a space. And then we have interactive elements that cover things like links, buttons, code blocks, copy buttons, all of those allow folks to interact with your content or perform actions in different ways. So these are some of the essentials that people rely on when using assistive technologies to navigate and interact with your site. So if we refer back to the principles of WCAG, operable includes headings. For folks to be able to infer the structure of your content, using appropriate headings is essential. Make sure that you're using headings hierarchy. Start with level one heading, move into level two heading, three, do not skip levels, so on and so forth. There is not one rule that says you can only have one level heading, but it's a consensus in the accessibility community that you should have one and only one level one heading in older documents. If you use, for example, Sphinx-based documentation, it not only allows you to generate HTML pages, but it also allows you to generate PDFs and EPUBs and other formats. If you try and use more than one heading, level one heading, sorry, in Sphinx, it's going to complain, because it has to have this compatibility with other formats, mostly latex and PDF, and I don't think it was intentional from an accessibility point of view, but it's It's a nice incident that forces you to be a bit more accessible. So that is the first thing that you can do as an author. Make sure that you're providing structure through using headings, breaking your content into sections. Links. This is probably one of my biggest pet peeves. Imagine that you're here at PyData Berlin, and you're trying to meet with one of your friends and say, hey, where are you, and you say, here. It's a nondescriptive here. It can be here, it can be here in the bathroom, here in Berlin, here in the conference centre. It's exactly the same when you are providing links or you're trying to redirect your user somewhere else. They should have enough context as to where that link, whether it's internal or external, going to take them, so try to use descriptive text. We also have being able to operate and navigate your website through other inputs, like your keyboard, for example, if you cannot use a mouse or through screen readers or voice control. So this is not something that you should be responsible for, but us that build the themes and the tools are responsible for. But I know sometimes, in the spirit of us making our documentation sites more stylistic or palatable, we inadvertently remove focus, like those focus rings or links underlined, and that hinders accessibility. One of the reasons is because, let's go back to the representation of the PyData Sphinx theme. Imagine you land on the home page, and then you want to go to the example gallery. That is your navigation goal. You want to find that link and go there. If you can scroll on your mobile device, or on your computer, or using mouse, more than likely, just scroll and click. That's two steps. For a blind person or someone with motor disabilities that cannot use a mouse or a scroll, that's how they navigate. So if I'm using just keyboard and tabbing, then my navigation goal, you can see the numbers, becomes a step 21. It's a huge difference from two steps, right, like from a two-action step. So we go back to this object that I mentioned before, headlines, landmarks, focus order. That is actually what all those numbers represent, like places in the landmarks and those focusable elements. There are some techniques that we can do with accessibility. This is again on us, the developers, of the themes that we can do to remove some of the friction. to know where people want to go, like this landmark. So sometimes we would add this skip to main content so that allows folks to skip all of those links in the navigation bar, so then they'll take them directly to the first link that is that PyData community, and that turns into something more reasonable like five steps versus 21 steps or 21 tabs. That's also why having descriptive link text is very important, because otherwise you're just going to be navigating through 30 here links. Then perceivable text alternatives, maybe some of you have heard about alt text. Whenever you have anything like images, videos, audio, data visualisations, you need to ensure that you have an alternate description so that folks that cannot interact through sound or images can fall back to this other input. Now the important thing is it is not just enough to say image or a screenshot of a black hole, but give enough context as to why that image or that object is there. So for example, if I were to go to the NumPy website, a suitable caption wouldn't be black hole. Sorry, a suitable alt text wouldn't be black hole, but it would be first ever black hole image generated by the Event Horizon Telescope, generated thanks to libraries such as NumPy, SciPy and MapLolib. This is contextualised as to why I am adding this, why I'm expecting my reader to get out of this image, and how it fits with the broader content. Perceivable also includes colour. I'm not going to talk about colour blindness because I think there are so many resources, but ensuring there is sufficient colour contrast that, again, don't remove the underlying from the links, because we want to have other visual cues or other cues that are not just colour. There are a lot of checkers out there that you can use to make sure that you're hitting contrast. There are other tools, for example, syntax highlighting is extremely hard to get right, and I know we all have our preferred syntax highlighting theme, because black versus light diverse, high contrast, but also ensuring that this has enough good contrast when highlighting is essential. My team and myself have been working on a library called accessible pigments, and that makes sure that the syntax themes that are there are actually meeting contrast and high contrast, and some of them are colour blind friendly, and those are to the fault that we are using now in PyData Sphinx. Writing style as well. If anything, also remember accessibility practices have some unintended good consequences. If you have good alt text, if you have descriptive links, if you have alternative text or input media or stuff like like that, that also helps with SEO. If you want people to find your content, accessibility is also a good way to do that. But in general, a lot of the recommendations that we're going to see, how do I write good technical documentation, are applicable to make your documentation more accessible. Use plain language. Avoid jargon. Don't use idioms. Introduce acronyms at the start. This helps especially for folks with cognitive disabilities. If you can, translate and localise your content. This is very important. On the developer side of things, in the themes, we can also localise landmarks. So, you get that double localisation. So, make sure to set the language when you're setting your websites. Use inclusive language. And this is a lot. I know you cannot do every single thing and make sure, like, learn everything on WCAG and do a lot of things. It's a lot of work. So, for example, on the PyDate Sphinx We recently did a massive overhaul to make sure that every single component there was screen reader and keyboard-friendly, so it's not in the latest official release, but if you go to development, you're going to see a significant improvement in this aspect. That touched translate localisation as well. That touched having to change a lot of the templates, so we're doing all of that work for you, so you can only focus on the authoring side of things. How do you keep yourself accountable? Take ownership of what you can take ownership of. Writing good alt text, using descriptive links, customise. We all like customising things. If I'm given a choice, I'm always going to make everything verbal, so I'm going to do it. But be careful and judicious about these changes that you're doing. Sometimes links, underlying links, we don't like them, but they serve a purpose. Sometimes we don't like focus rings because they look a bit jarring. They serve a purpose. Getting colours across the whole theme is incredibly hard. So if your theme has good accessible defaults, rely on some of those defaults as much as possible. Solicit feedback from people with disabilities. This is absolutely important. It doesn't matter if we are trying to follow WCAG or a tag or whatever we are trying to follow, but if we do not listen to the people with disabilities or people that we are directly affecting and excluding with our tools, it means nothing. So something that has helped us a lot as we're building this is having accessibility-specific tags, having user experience-specific labels on our issues so that people know, and give consistent updates in our change logs when it comes to accessibility, so people know we're actively working on it so that we get feedback and we signal that we are open to listen to people with disabilities. There are a lot of tools as well that you can use as a little bookmarklet or that you can use online and will help with a lot of these things. We're going to tell you this link is broken, this image is missing all things, this has not enough contrast to try and use them. Polypane is one of my favourite things and it does everything, but I spend a lot of time working on this website and JupyterLab and other tools. whatever it is that you want. A checklist, standards, style guide, something. But don't let it slip through. The same way that you check for your style, you check that your doc strings have style consistency, the same way that you make sure that your documentation gets read, make sure that you're following your own standards that you're setting for yourself. So, I think I'm not going to have time, but I'm around, I'm very set to find, like, we're going to continue working a lot on some other themes as well and stuff to keep making them more accessible. And also, we're going to be running, as my fabulous team at Cancer Labs and myself, some accessibility clinics or some accessibility workshops, mostly focused on data visualisation, How can you make your data visualisations more accessible, more inclusive? Using Python, using all the tools that you love and use on a daily basis. Some guided sections on conducting accessibility checks on your sites, like learning how to use some of the assistive tech and some of the developer tools as well, and integrate with your CI processes. That is how you can get hold of me, or probably in one of the Python-related events. Yeah. Just in time. Thank you.

Speaker 2 [30:13]

Thank you, Tanya. There are quite a lot of compliments on your particularly choice of slides as well as the motivation behind your font. So maybe could you quickly tell people about why did you choose a regular font for your presentation?

Speaker 1 [30:36]

A regular font. It's easy to read, so that is also something. Usually font are more readable, so they're easier to follow through for folks with dyslexia or whatnot. I don't like adding a bit of flair with headings and whatnot, but they tend to be quite big fonts or quite big letters, so that helps. In general, I try to always avoid very jarring colours like red and orange and whatnot because people with cognitive disabilities and sensory overload tend to struggle with that, so sometimes simple is pretty as well.

Speaker 2 [31:19]

Okay, thank you. Maybe one more question and we end today's session because we are running also very tight in time. So are there any tools that can warn about accessibility issues which can be included in CICD? I'm sure you gave a lot of links, but it would be nice to also elaborate on that.

Speaker 1 [31:39]

I'm going to have to share my slides online. I'm very sorry. But if you look in the middle there, there is one called XCore. You can integrate, if you already use something like Playwright for testing, you can use XCore. There is another tool called Pali, that is P-A-11-Y, sorry, I was just forgetting this. You can plug and play that directly on your CI. Lighthouse, probably some of you are using Lighthouse already for some performance stuff, but it gives you also some insights on accessibility. I do want to be very, very careful, because when we audit for accessibility and test for accessibility, we need to really use a very, very wide range of tools, because we have to test and assess for a very wide range of interactions. So if you're using tools like XCore or Lighthouse or Pali, they're only going to catch a very small subset of, well, easy to test features. So probably it's going to catch up to 30% of the accessibility issues and then the rate has to be checked manually. But I suppose that's good. It's a good start. Thank you.

Speaker 2 [33:05]

Okay. I think we will close on with that. Let's thank again Dr. Tanya once again for her interesting talk.