Pycon.de: a11y need is love (but accessible docs help too) - Smera Goel¶

Tags: pycon, python

(One of my summaries of the 2025 pycon.de conference in Darmstadt, DE).

a11y = AccessibilitY.

Documention is an important part of every project. But what does it mean to write documentation for everyone?

You can make a “maslov pyramid” for documentation. Accurate content and install instructions are the basic necessity. For many writers, accessibility is somewhere at the top: a nice cherry when you get around to it.

But for some people it is a basic necessity. Accessibility means removing barriers. Making sure people can use what you build.

And: with accessibility you often think about blind people or someone without an arm. But if you solve a problem for the arm-less person, you also solve it for someone who broke their arm. Or someone holding a baby.

Common accessibility problems in docs:

• Low contrast text.

• Poor heading structure.

• Unlabeled buttons/links.

• No visible focus indicators.

Every one of those problems adds some friction for everyone. And… docs are often read when there’s pressure to fix something, so any fiction is bad.

Now, how do you determine if your docs are accessible? An audit can help. It can be manual or automated or a mix. There are plenty of free tools: microsoft accessibility insights for web is one of the many tools (and the one she will use). The gold standard of testing, though, is to do real user testing. The best insights come from disabled users.

As a test she looked at the pydata sphinx theme. When they started improving it, they converted the output of microsoft’s accessibility test into issues. For such issues, be specific. Include the page, element and what’s failing. Reference an accessibility standard if possible. A screenshot or a short screencast.

Common problem: brand colors. Your project or company has a specific color already and if you use that color directly, it often isn’t accessible. There just is not enough contrast. The solution can be to take the color you want and to create lighter and darker versions of it.

Hover states problems are also common. Often there’s a slight change in color to signify that you’ve clicked something, but that’s often not clear for colorblind people. Use borders, underlines, etc.

They’ve got a “figma” explanation if you use figma.

She then did a quick investigation of the pycon.de website with microsoft’s accessibility tool. Most of the clearest problems were due to color contrast. White text on light gray, white text on light green, white text on yellow, etc. White on gray had an contrast ratio of 1.6:1, where 3:1 is recommended.

What can you do yourself?

• Run a quick audit on your docs.

• Review focus styles and heading structure.

• Share or reuse the pydata design system.

• Encourage accessibility discussions in your project.

• Open an bug in your project for encouraging collecting accessibility issues.

Photo explanation: picture from our 2024 vacation around Kassel (DE)