Rework Notebook 7 docs accessibility section

[andrii-i]

Problem

As pointed out in jupyter/notebook-team-compass#24 (comment), the accessibility section in the Notebook 7 docs can be improved.

Comment by @trallard

_Originally posted by @trallard in https://github.com/jupyter/notebook-team-compass/issues/24#issuecomment-1635813804_ Hey folks. Since the blog post was mentioned at the Jupyter accessibility call and feedback was requested, I thought I would share some thoughts.

Upon first read of the blog post, I did not notice anything accessibility-related but instead, the post links to the New features in Notebook v7 documentation which includes a section on WCAG compliance.
The section excerpts and links to another blog post published a few months back.

TL;DR

• I think it is great that folks are trying to make accessibility-related work and improvements more visible in the official documentation
• However, such documentation must be accurate, transparent, and aligned with the Jupyter community's inclusion goals. After rereading the blog post and based on all the accessibility work in flight and completed within Jupyter, I do not believe the current Notebook’s accessibility documentation meets those requirements (more details below, including suggestions on how to best present this information).

The long version

Since the content in the Jupyter Notebook’s documentation is a small excerpt of the blog post in Medium - I will center my feedback on the latter as readers are directed to it for more information (from the Notebook docs).

1. The blog post includes biased and problematic language, such as:

   1. population has a disability that may impair their ability to use online services [^1]
   2. it requires accommodating a broad range of disabilities, including vision, motor, and cognitive impairments
   3. users who have specific needs

   The last phrase is a variation of the often-used "special needs" phrase. Us people with disabilities have the same access needs to physical and online spaces as everyone else. Therefore, they are not special needs but rather access needs.
   All these phrases somehow imply that something is wrong with us that needs fixing, while in reality, we cannot exercise our access rights (because it is by law a right) due to multiple systemic, attitudinal, and environmental barriers.

   If we don’t want them to be excluded from learning sciences, technology, and engineering,

   In the same spirit, it deflects the responsibility from the Jupyter community to the disabled community. Our goal is disability justice and inclusion, and to do so, we must first acknowledge that the many barriers limiting the participation of people with disabilities in STEM are there because of us, the ones creating and maintaining the tools.
   We (the ones working on accessibility) are not the saviors of the disabled community nor preventing their exclusion, but rather are working towards removing existing barriers that have for a long time excluded people with disabilities from our communities.

   Note that certain communities use the term impairment (for example, visually impaired), but this is highly contextualized, and we should always check how people prefer to define/refer to themselves.

2. Some information is not entirely accurate, such as:

   Improving the accessibility of Jupyter had long been impeded by significant obstacles. The primary obstacle was that the text editor underlying the Jupyter Notebook (CodeMirror 5) had major accessibility issues.

   I would class the inaccessibility of CodeMirror as a considerable obstacle, but not the primary obstacle for Jupyter tools accessibility. Implying that the inaccessibility of CodeMirror was the primary obstacle for Jupyter accessibility is deflects responsibility from the Jupyter community and the many accessibility issues that have been reported and ignored for years.

   This can be supported through the multiple audits carried out on JupyterLab and Jupyter Notebook:

   • Notebook v7.0.0 for WCAG 2.1 audit (March 2023)
   • Notebook 7 prerelease keyboard navigation review (October 2022)
   • JupyterLab Screen reader with keyboard shortcuts audit (June 2019)
   • JupyterLab v2.2.6 for WCAG 2.1 audit (November 2021)
   • JupyterLab 3.4.3 Zoom Audit (August 2022)

   Through those audits, the community has unveiled many accessibility issues unrelated to CodeMirror, but to the JupyterLab and Jupyter Notebook UIs. Most of them result from considerable accessibility-related technical debt accumulated over the years, lack of accessibility knowledge, accessibility testing and UX/UI design (until recently), and minimal work with the disabled community to understand their needs and ensure we are building products that are usable and accessible to them.

3. Information is incomplete or not detailed enough, such as:

   we made an automated audit of the accessibility of Notebook 7 with these changes, and found that the number of warnings and errors reported by Axe Auditor went down from several hundreds to a few dozen

   we were able to make the Notebook 7 codebase pass the Axe Auditor tests with zero error or warning.

   While some automated audits, or rather automated diagnoses, were performed, there is little depth or information about them. Information that is missing is:

   • What was the methodology used to perform the audits?
   • There is no mention of WCAG (Web Content Accessibility Guidelines) or which criteria were considered.
   • There is no mention that automated tests only catch up to 30-50% of accessibility issues.
   • How do these improvements align with WCAG conformance, and how do they impact people with disabilities?

   It is estimated that 15% of the population has a disability

   This is a rather conservative number; some sources cite 15% others sources refer to numbers around 20-25% percent. For example, the UK government cites 22% of the population has a disability, while the CDC reports 27% for the US, which can be significantly higher in emerging economies.

   If we account for people with temporary and situational disabilities, this number is also significantly higher.

4. Misleading information or data misrepresentation:

   The below image is presented on both the blog post and the Notebook documentation. I have already covered the lack of supporting information for such automated checks.
   There is insufficient context around this image (in text or alt-text); therefore, this is left up to the reader's interpretation.

   

   Leaving the interpretation of this image up to the reader is problematic for a few reasons:

   1. For the non-accessibility savvy person, this image might be interpreted as the Jupyter Notebook is now fully accessible, which is not the case.
   2. This content is in an official Jupyter source, the Notebook documentation, and therefore, millions of users will take this at face value. This is problematic because it is inaccurate and could damage the community's trust in the project. I have seen other projects or tools making similar claims, only to be found that this was inaccurate, eventually leading to a loss of trust in the project and a break with the disabled community.
   3. There are a number of organizations with compliance requirements; having this type of information can lead to them making decisions that are not in the best interest of their users or the disabled community. And that can lead to legal issues for the organization and a loss of trust among its members.

   CodeMirror 6, a complete rewrite of the text editor with a strong focus on accessibility

   This is a claim I have tried to get more information on CodeMirror docs, discussion forums, and the such and have not found solid details on. I still have to find what that "strong focus of accessibility" means. Or when they say it is more accessible, I still do not know accessible how or to whom. I would like to know if these claims have been tested in Jupyter Notebook beyond the automated checks and, if so, how and what were the results.

   The work by Johan Mabille at QuantStack on migrating JupyterLab to use CodeMirror 6 was funded by Two Sigma.

   AFAIK this was not a single individual work but a team effort. I would like to see the other contributors recognized for their work. I know of more folks involved in this effort, and only one individual is mentioned in the post; I assume this was an oversight?

Recommendations 📝

Since it seems we all agree on making the accessibility work visible, we should do it in a way that transparently and accurately reports the accessibility and usability status of Jupyter Notebooks. I suggest doing a complete re-write of the Jupyter Notebook v7 accessibility docs as a resource if its own rather than depending on an external blog post. By doing so, this could become the foundation of an evergreen resource accurately representing the status of the Jupyter Notebook’s accessibility and usability.
As for Notebook v7 there are other accessibility improvements that have been made and are not mentioned anywhere, the only one captured is the CodeMirror migration and I believe all the other contributions deserve mentioning too.

Upon rewriting, the documentation should contain at least the following information:

• A date/version (s) to which the report/data refers to
• WCAG conformance status
• Compatibility with browsers and assistive technologies
• Technical specifications
• Limitations
• Approaches to accessibility testing and auditing
• What we are working on in terms of accessibility

You can find an example of such an approach in the JupyterLab Accessibility Statement. Which we hope to include in the JupyterLab documentation soon.

Supporting resources 📖

• CDC Disability impacts us all - statistics on disability in the US
• UK disability statistics: Prevalence and life experiences
• Limitations of automated (accessibility) testing

Proposed Solution

Tasks

Preview Give feedback

1. Update accessibly compliance section in the docs #6982
   documentation enhancement +2
   
2. Rework and reinstate it