What can we upstream?

[isabela-pf]

Problem and context

In today's meeting #38 we discussed some ideas of what we felt should be the focus of contributing in the next few months. I'm starting this issue to provide a location for us to gather our thoughts around.

From the beginning, this team's intent was to upstream work from this project to improve the static notebook experience for users. As we approach the end of our work cycle, we need to collect

• What we've completed
• Where/what projects it may be relevant to
• And what is feasible to contribute

in order to decide what it is we will be upstreaming. This discussion can also record of things we thought would be good contributions, but do not have resources to commit to making now.

Possible solutions

While there are a few ways we could choose to approach it, I think the result is clear: come away with an ordered list of contributions to make. I'm open to other ideas if people have done this another way.

Acceptance criteria

This issue can be closed when

• The team has agreed upon a set list of work to be contributed upstream
• The team has agreed (and written here) who will lead each of those upstream contributions
• Relevant contribution methods have been posted (they will likely all be PRs, but I'm leaving it open)

I don't think we need to wait for everything to be merged to close this issue; timelines for merging greatly vary per project.

Tasks to complete

• List ideas of what's been done or what people think might be good contributions
• Mark that list with the status of the contribution (ie. 'ready to contribute', 'in progress', 'not started', or something similar), the upstream(s) that are relevant, who is interested in leading that contribution, and whether the impact is STScI-only or more broad
• Based on the notes, choose what contributions we want to prioritize in what order (I think this should be an ordered list)
• Make our way through the contribution list

[isabela-pf]

And I have some ideas of what we could contribute!

On the development side

Bear with my possible inaccuracies as I try to describe work I didn't do.

• Add enhanced contrast changes for the notebook UI to nbviewer's styling library (I'm not sure if this is a library or where it lives)
• Add anchor tags to rendered notebook headings (also nbviewer-related)
• Add a set of keyboard navigation options to nbviewer (to be determined from further tests; we have a few developed now)
• Replace the current syntax highlighting theme used in nbviewer with one designed for better contrast (like one of the options at ericwbailey/a11y-syntax-highlighting
• Add an ordered list table of contents to the top of nbviewer (based only on content headings)

On the user testing side

• Make a section in jupyter/surveys to describe and link to this repo so the research stays orbiting the relevant ecosystem
• Make changes to the existing STScI notebook authoring guide to include accessibility considerations and best practices
• Make changes to the existing STScI tutorial-writing tutorial notebook to address accessibility issues we found (and maybe include best practices)
• Make a standalone notebook authoring recommendation based on our usability testing. This could live here and also be contributed to projects that care about writing notebooks now or in the future.

[isabela-pf]

Another option came up about upstreaming to the way GitHub rendered notebooks, which has had recent updates.