accessibility
accessibility copied to clipboard
jupyter
Accessibility docs best practices
In one of the past JupyterLab accessibility meetings we received feedback that not only do accessibility-specific docs help people better use software, but that some users decide whether or not to even try using a piece of software based on whether or not there is an accessibility section to its docs. Since documentation is often left as the last step of our process and it sounds like this might be more important than we anticipated, I wanted to bring it up now.
I haven’t found accessibility-specific docs on any Jupyter project, so I don’t think we have best practices for these types of docs. I’m also betting that we will run into questions we haven’t with the general docs and will find answers worth recording.
This issue is open for discussion! Some ideas of what I think might be helpful are:
- Existing accessibility docs we can use as examples
- General accessibility docs best practices
- General accessible writing practices
- Proposed organization/headers (should it be sorted by user need? by whether or not an assistive device is used? etc.)
- Anything else you come across that ties together accessibility, writing, and documentation!
Full transparency, I spend my time around Jupyter almost exclusively on JupyterLab at the moment but I thought this topic might be helpful to projects across our community.
Shared by @trallard
- Someone recommended this article in a Discord for OSS https://letters4sneha.medium.com/the-tech-writers-journal-7-creating-accessible-documentation-eb2c011ac83c
- I also found this guides from opendocs to do audits for documentation maturity and completeness https://github.com/google/opendocs/tree/main/audit
adding to this, it would be nice to aggregate accessibility changelogs here.
Would it be OK to start a Jupyter Book style documentation for this repo to help keep track of all this?
(I am happy to help with docs, I don't think it should be a huge amount of effort)
what do y'all think about using discussions, now that we have them, to collect documentation https://github.com/jupyter/accessibility/discussions/29
I think that more free-form discussions can be a great way to collect documentation and information in a faster way than maintaining a full Sphinx site. (that said, another place to consider is the Jupyter community forum, which will be more visible to a broader group of people)
Also just a note, we do have a special category for a11y here: https://discourse.jupyter.org/c/special-topics/accessibility/29
This is a reference comment for ideas I'd like to review when we get a chance to solidify this work. Totally subject to edits.
- Writing documentation with neurodivergent oss contributors in mind
- Let me learn
- Write the Docs accessibility guide
- Best Practices for Image Text Alternatives
- An Alt Decision Tree
- Accessibility Concerns for Content Staff
A quick signal boost on this one - we recently merged a PR in the jupyter docs that added alt text to several images ( https://github.com/jupyter/jupyter/pull/607). However I'm a bit worried that people in general don't know what practices to follow for alt text, or how to reason about them, and that this will create another barrier for people to contribute to documentation (which we already have an extremely hard time getting people to do).
It might be helpful to point people to some practices and information to lower this confusion and barrier a bit. That said, I also think that these resources should consider the typical perspective of a jupyter contributor. They should start with a "good enough" practices that are suitable for a stressed out and overworked contributor with no training in a11y, not best practices that would be suitable for a team with dedicated resources. They could include more "best practices" information as well, but the most visible content should focus on the few easiest things to follow to make marginal improvements.
Maybe there's a "getting started" section that covers the 5 easiest and most impactful things that people can do to help boost accessibility in the jupyter ecosystem.
May I ask a clarifying question? When we talk about an accessibility-specific section of the docs, who is the intended audience for that section? Are we talking about a section for documentation writers, a section with tips, guidelines, best practices for writing docs that are more accessible? Or are we talking about a section of the documentation intended for users with disabilities who are looking for tips, tricks and instructions on how to adapt the app to their needs?
In my mind, at least one section would be for open source developers to make them more likely to follow some best-practices in building tools and documentation for Jupyter.