Accessible Notebooks Hackathon

Notebooks for All: Jenn Kotler, Patrick Smyth, Isabela Presedo-Floyd, Tony Fast, Erik Tollerud

Welcome

Accessibility:

a Quick Overview

​

Accessibility

Designing experiences for people with the broadest set of capabilities, including people with disabilities.

​

“curb cut effect”

​

Topics to explore more: universal design

​

STEM careers have significant accessibility barriers

• Disabled students commonly drop out of science majors because pivotal tools don’t work with assistive tech
• There is no inherent reason they should not be able to work in science, the tools could be built accessibly

​

Inaccessible notebooks one of these major barriers

Notebooks

for All

Project Background

Notebooks for All Project

A research collaboration between Space Telescope Science Institute, �Iota School, Quansight Labs, and the broader Jupyter community.

You can find resources on the project’s GitHub repository

​

Goal: We aim to learn and publicly document:

• Where notebook reading and navigation workflows fail disabled people
• What would be the preferred experience
• What technical constraints influence the user experience

Problem solving: Iterative Process

​

Our workflow is cyclical!

• Usability testing- meeting with people that use assistive tech and listening to their feedback.
• Write results
• Tasks
• Update notebooks with fixes
• Repeat: another round of usability testing…

Authoring Tips

Notebook formats & accessibility

The editable notebook format

This is inaccessible and has many obstacles to navigating the UI or to edit cells.

​

Uneditable notebooks exported to HTML

This is somewhat accessible because HTML is built for web accessibility. �While there are issues, people tend to succeed in accessing a majority of �exported notebooks.

​

The content of notebooks

This can be totally accessible, if the authors are mindful of some of the following. This is where you can act now!

Consider these tips when creating �a Jupyter notebook you plan to �share publicly

​

This list is distilled from feedback we received from blind and visually impaired developers

Organization

Give context at the beginning.

Be sure to include:

​

• A title.
• This should be the one H1 you use—it should be at the top.
• A summary of the notebook.
• A table of contents as an ordered list.
• The author(s) and affiliation(s)
• The date and time first published.
• The date and time last edited.
• A link to the notebook’s source

Use your Markdown

​

• Use markdown as intended. This produces proper HTML.
• Use content headings. There is only one H1. Do not skip heading levels.
• Begin markdown cells with headings. Start the document with a markdown cell beginning with a h1 heading

Skipping heading levels creates an unclear navigation experience for people reading the notebook.

Images

Image descriptions

​

Describe what is in the image as it is relevant to the rest of the notebook. Add alt text if supported:

• Image and Figure tags support the alt attribute.
• Some visualization libraries support the alt attribute.
• Other visualization libraries do not support the alt attribute.
• When in doubt, describe the image in surrounding text. �This can be a caption tag or a separate paragraph.

If there’s text inside an image, include it in the description.

Further resources on image descriptions.

Alt Text - A definition

​

HTML element that allows a screen reader to describe what an image is.

Visualization - Alt Text

​

Text inside generated graphs cannot be read by a screen reader and may be too small to read with low-vision. The same information needs to be in alt text or captions.

When writing alt text for a plot, include:

• Type of visualization (bar chart, scatter plot, etc).
• Title, axis labels and range, key / legend.
• General explanation of the visualization’s significance to surrounding info.

Including only this image is not enough because the titles and axis are not accessible

Visualization - Labels

​

Label your visualization.

• Include a title. It should appear visually and as a plot property.
• Label axes & their tic-marks.
• Include legends.

Visualization - Colors

​

• Colors need good contrast (the relative difference in tonal hues).
• Be cautious of low opacity, thin lines, and similar color combinations, such as light-gray on white.
• Consider plotting in only black and white. You can always add color in later.
• Don’t rely only on color to convey information. Include labels. Consider using a mix of color and patterns to differentiate values.

Because the lines on this graph have been given a low opacity, some of the colors do not meet contrast standards

Visualization - Conveying the data

​

• It can be very helpful to link to a file containing the original data, or if possible include a data table near the plot so it can be accessed in a non visual way
• Include a sonification for a plot. You can use Astronify to represent time series and spectral astronomy data.

Text

Use descriptive link names

​

Do not put links on:

“Click here!”

Do put links on words describing where the link leads:

“More resources in the Notebooks for All Github repository.”

Use ‘plain’ language

​

• Define acronyms the first time you use them and use them sparingly
• Only use field-specific terms when needed. Use approachable language when the terms aren’t critical to understanding the rest of the document or related literature.
• More general tips on stylistic choices with accessibility considerations can be found on Google’s Developer Documentation style guide.

Code

Lead into code cells

​

• They can be labelled content headings (ie. an imports cell can be preceded by a markdown cell with a header “Imports”)
• Tell what the cell should do before it is done. Usually this is in a markdown cell before, but it also could be a comment in the code cell.
• Comment on long stretches of code.

Code

​

• Use a syntax highlighting theme that considers accessible contrast
• Do not list several different ways someone could complete the task unless that is the point of the notebook. Focus on what you are doing first, and mention alternates later if needed.

​

Before a code cell, describing the end goal, relevant functions, and variables can help. Source: NumPy Tutorials

Other Content Types

Notebooks are full of creative ideas

This includes videos, sonifications, interactive widgets, and more. In general:

• Use titles. Long or complex content may benefit from summaries.
• Things that move can't have flashing more than three times per second.
• Nothing should autoplay.
• Any visual controls need to have enough color contrast and be labeled.
• List or link the source of the content.
• Videos need captions/subtitles and transcripts.
• If it is needed to understand the rest of the notebook, the information needs to be accessible outside of the interactive widget as well.

When in doubt, write it out.

​

Important Take-aways

Summary

​

• Include context and descriptions.
• Interactive areas need controls, labels, and adequate contrast.
• Provide links for more information or sources where applicable.
• Use Markdown!
• Make sure what you create is perceivable, operable, and understandable.

Questions?

Prepping to Hack :)

Hack Activity - 1 Hour

Evaluating a notebook for Accessibility

​

​

Let’s apply the authoring tips to real-life Jupyter Notebooks

1. Pick your notebook, and export it to HTML�

​

Our use one of these Space Telescope exported notebooks:

• https://eteq.github.io/notebooks-for-all/Imaging_Sky_Background_Estimation.html

​

• https://spacetelescope.github.io/hellouniverse/notebooks/hello-universe/Classifying_TESS_flares_with_CNNs/Classifying_TESS_flares_with_CNNs.html#

​

2. Evaluate your notebook using the accessibility checklist�

​

• Choose a section of the list that interests you, ex: plots
• Use the checklist to review your notebook for that topic, does the notebook follow the best practices listed?

​

https://github.com/isabela-pf/notebooks-for-all/blob/authoringrecs1/resources/event-hackathon/notebook-authoring-checklist.md

​

3. As a group, use the final 10 minutes to discuss��

​

• What was the most common accessibility issue you encountered?

​

• What content immediately checked as accessible?

​

• What surprised you the most in this process?

​

• Do you think you’ll change anything when authoring notebooks or documents going forward?

​

Break-out Rooms

​

​

• Quick introductions
• While working on your task, please discuss ideas, ask questions, and collaborate!
• In the last 10 minutes, discuss which issues you found most commonly throughout your notebooks
• Pick a person to report back to the whole group

​

After 1 hour, we will reconvene and discuss

Questions?

Let’s Hack :)

But first… a 5 Minute Break

​

​

​

Post-Hack

Discussion

Discussion Questions

• What was the most common accessibility issue you encountered?

​

• What content immediately checked as accessible?

​

• What surprised you the most in this process?

​

• Do you think you’ll change anything when authoring notebooks or documents going forward?

Thanks for attending!

Notebooks for All: Jenn Kotler, Patrick Smyth, Isabela Presedo-Floyd, Tony Fast, Erik Tollerud