hack.html

---
layout: default
title: "Notebook Accessibility Minihack"
---

<div class="sections">

  <section style="margin-bottom:0">

    <div class="container col-xxl-12 px-4 pt-5">
      <div class="row flex-lg-row-reverse align-items-center g-5 pt-5">
	<div class="col-4 col-sm-4 col-lg-4">
	  <!-- <img style="width: 20rem" src="assets/images/stsci_logo.png" class="d-block mx-lg-auto img-fluid" alt="Space Telescope Science Institute logo" width="700" height="500" loading="lazy"> -->

	</div>
	<div class="col-lg-8">
          <h1 class="display-5 fw-bold lh-1 mb-3">
	    Notebook Accessibility Minihack
	  </h1>	  

          <p class="lead">
	    A one-hour exercise to evaluate HTML Jupyter Notebooks for better accessibility
	  </p>
          <p class="lead"><a target="_blank" href="index.html">View Event Details</a></p>	  	
          <div class="d-grid gap-2 d-md-flex justify-content-md-start">

          </div>
	</div>
      </div>
    </div>
  </section>

  <section class="table-contents" id="toc">
    <h2 class="display-6 lh-1 mb-3">
      Contents
    </h2>

    <ul>
      <li><a href="#overview">
	Overview
      </a></li>
      <li><a href="#step-1">
	Step One: Choose a Notebook
      </a></li>
      <li><a href="#step-2">
      Step Two: Evaluate Notebook
      </a></li>
      <li><a href="#step-3">
	Step Three: Review and Share
      </a></li>
      <li><a href="#step-infinity">
      Step ♾: Extra Credit / After the Hackathon
      </a></li>
      <li><a href="#checklist">Accessible Authoring Checklist</a></li>
    </ul>
  </section>

  <section id="overview">
    <h2 class="display-6 lh-1 mb-3">
      Overview
    </h2>
    <p>
      In this one-hour exercise, we'll apply our accessible notebook authoring tips to real-life Jupyter Notebooks. We'll be focusing on notebooks exported to HTML, a format that is partially accessible to screen reader users by default.
    </p>

  </section>

  <section id="step-1">
    
    <h2 class="display-6 lh-1 mb-3">
      Step One: Choose a Notebook
    </h2>

    <p>
      You have three options for picking a notebook to evaluate during this minihack. (If you're not sure about this step, pick one of the default notebooks under the first option.)
    </p>

    <h3 class="lead">
      Option 1
    </h3>
    <p>Choose one of the notebooks below. This is the default option.</p>

    <div style="margin-top:2em" class="container">
      <div class="row">
	<div style="text-align:center" class="col-4 col-md-3 mx-auto">
	  <a class="btn btn-primary btn-lg px-4 me-md-2" target="_blank" href="https://spacetelescope.github.io/jdat_notebooks/notebooks/asdf_example/asdf_example.html">ASDF Creation</a>

	</div>
	<div class="col-md-9 col-8">
	  <p>
JWST data files make use of the Advanced Scientific Data Format. This notebook shows how to create an ASDF (Advanced Scientific Data Format) file from a FITS file.<br><br>
	  </p>
	</div>
      </div>

      <div class="row">
	<div style="text-align:center" class="col-4 col-md-3 mx-auto">
	  <a class="btn btn-primary btn-lg px-4 me-md-2" target="_blank" href="https://spacetelescope.github.io/hellouniverse/notebooks/hello-universe/Classifying_JWST-HST_galaxy_mergers_with_CNNs/Classifying_JWST-HST_galaxy_mergers_with_CNNs.html
">Galaxy Mergers</a>
	</div>
	<div class="col-md-9 col-8">
	  <p>
An example of building, compiling, and training a convolutional neural network on simulated astronomical data. The CNN classifies JWST-HST galaxy mergers.<br><br>
	  </p>

	  
	</div>
      </div>    
    </div>

      <h3 class="lead">
	Option 2
      </h3>
      <p>
	Use a notebook created by you or your organization. Since we'll be evaluating the HTML export of the notebook, you will first want to open the notebook in Jupyter, then Choose `File > Download as > HTML (.html)`. This will export your notebook to HTML in the same folder as the notebook. Once you're done, open the notebook in a web browser such as Chrome before going on to the next step.
    </p>
    <h3 class="lead">
      Option 3
    </h3>
    <p>
    Select a different notebook from an STScI project. The HTML notebooks can be found using the links on the left side of each project page. Screen reader users can navigate by list or list item to jump right to the lists of notebooks.
    </p>
    
    <div style="margin-top:2em" class="container">
      <div class="row">
	<div style="text-align:center" class="col-4 col-md-3 mx-auto">
	  <a class="btn btn-success btn-lg px-4 me-md-2" target="_blank" href="https://spacetelescope.github.io/jdat_notebooks/">JDAT Notebooks</a>
	</div>
	<div class="col-md-9 col-8">
	  <p>
	    The jdat_notebooks repository contains notebooks illustrating workflows for post-pipeline analysis of JWST data. Some of the notebooks also illustrate generic analysis workflows that are applicable to data from other observatories as well. This repository and the notebooks are one component of STScI’s larger Data Analysis Tools Ecosystem.
	  </p>
	</div>
      </div>
      <div class="row">
	<div style="text-align:center" class="col-4 col-md-3 mx-auto">
	  <a class="btn btn-success btn-lg px-4 me-md-2" target="_blank" href="https://spacetelescope.github.io/hellouniverse/intro.html">Hello Universe</a>
	</div>
	<div class="col-md-9 col-8">
	  <p>
	    Hello Universe is an initiative at MAST to provide a space for applying machine learning (ML) algorithms to astronomical data. The first set of notebooks are designed to span a range of ML techniques, and to highlight MAST mission data, including user-contributed high-level science products (HLSPs).
	  </p>

	  
	</div>
      </div>    
    </div>

  </section>

  <section id="step-2">
    <h2 class="display-6 lh-1 mb-3">
      Step Two: Evaluate Notebook
    </h2>

    <p>
      Once you've chosen a notebook:
    </p>
    <ul>
      <li>Choose some criteria from the notebook authoring tips document. For example: focus on the notebook’s plots. Pick whichever area is most interesting to you. </li>
      <li>Take a look at your chosen notebook and evaluate whether or not the notebook follows best practices for authoring notebooks in that area. </li>
      <li>You may wish to divide up some of the main areas of concern within your breakout group—for example, one group might evaluate headings while another looks at code formatting.</li>
      </ul>
  </section>

  <section id="step-3">
    <h2 class="display-6 lh-1 mb-3">
      Step Three: Review and Share
    </h2>    

    <p>
      When we regroup with the rest of the participants, we'll consider each groups answers to these questions:
    </p>
    <ul>
      <li>What was the most common accessibility issue you encountered?</li>
      <li>What content was already accessible?</li>
      <li>What surprised you the most in this process?</li>
      <li>Do you think you’ll change anything when authoring notebooks or documents going forward?</li>
    </ul>
    <p>
      We have created a <a href="https://docs.google.com/document/d/11_DkoAATp33AVrrPqfkhABLoR0gfR8F6lVMkm2D_COs/edit?usp=sharing" target="_blank">collaborative Google doc</a> where you can share your thoughts and see responses from other breakout rooms.
    </p>
    <p>
      Before returning to the main Zoom room, please choose a member of your breakout room who would be comfortable presenting the results of your discussion.
    </p>
    


  </section>
  
  <section id="step-infinity">
    <h2 class="display-6 lh-1 mb-3">
      Step ♾: Extra Credit / After the Hackathon
    </h2>
    <p>
      If you're feeling ambitious or looking for a more direct way to contribute your thoughts and results to STScI (or your organization), here are some ways to make a difference:
    </p>

    <ul>
      <li>
	If you have just audited a JDAT notebook, the HTML Jupyter Notebooks on the left side of the page are hosted in their own individual repositories on GitHub. You can find the repository in the table on the <a href="https://spacetelescope.github.io/hellouniverse/intro.html" target="_blank">JDAT project page</a> and either <a target="_blank" href="https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue">open an issue</a> or <a target="_blank" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request">start a pull request</a>.</li>
      <li>
	If you audited a Hello Universe Notebook, you can visit the <a target="_blank" href="https://github.com/spacetelescope/hellouniverse">repository containing all Hello Universe notebooks</a> and either <a target="_blank" href="https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue">open an issue</a> or <a target="_blank" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request">start a pull request</a>.</li>
      <li>If you're not experienced with GitHub, you can also use Google or visit the <a target="_blank" href="https://www.stsci.edu/">STScI website</a> to find individuals or groups connected to your notebook and send them an email. Feel free to <a target="_blank" href="index#contact">reach out to the event organizers</a> for assistance.</li>
      </ul>

</section>


<section id="checklist">
  
    <h2 class="display-6 lh-1 mb-3">
      Accessible Authoring Checklist
    </h2>

<p>Whether a Jupyter notebook is usable for disabled people can vary widely—it depends on how the document is set up and presented. Notebook authors can use writing and publishing techniques to ensure their notebooks’ content is more accessible.</p>

<p>This checklist is based on the <a href="https://github.com/Iota-School/notebooks-for-all/blob/main/resources/event-hackathon/notebook-authoring-checklist.md" target="_blank">draft authoring tips</a> from the <a href="https://github.com/Iota-School/notebooks-for-all" target="_blank">Astronomy Notebooks For All team</a>.</p>

  <div class="table-contents" >
      <ul>
	<li><a href="#organization">Organization</a></li>
	<li><a href="#images">Images</a></li>
	<li><a href="#visualizations">Visualizations</a></li>
	<li><a href="#text">Text</a></li>
	<li><a href="#code">Code</a></li>
	<li><a href="#other-content">Other content</a></li>
	<li><a href="#videos">Videos</a></li>
	<li><a href="#sonifications">Sonifications</a></li>
	<li><a href="#interactive-widgets">Interactive Widgets</a></li>
	</ul>
  </div>

  <div class="checklists">

  <h3 id="organization">Organization</h3>
<p>At the beginning, a notebook should have:</p>
<ul>
<li> A title in the form of a <code>h1</code> (<code>#</code> in Markdown).</li>
<li> A brief summary of the notebook.</li>
<li> A table of contents in an ordered list (<code>1., 2.,</code> etc. in Markdown).</li>
<li> The author(s) and affiliation(s) (if relevant).</li>
<li> The date first published.</li>
<li> The date last edited (if relevant).</li>
<li> A link to the notebook’s source(s) (if relevant).</li>
</ul>
<p>Throughout the notebook</p>
<ul>
<li> There is only one H1 (<code>#</code> in Markdown) used in the notebook.</li>
<li> The notebook uses other heading tags in order (meaning it does not skip numbers).</li>
</ul>
<h3 id="images">Images</h3>
<ul>
<li> All images (jpg, png, svgs) have an image description. This could be
<ul>
<li> Alt text (an <code>alt</code> attribute)</li>
<li> Empty alt text for decorative images/images meant to be skipped (an <code>alt</code> attribute with no value)</li>
<li> Captions</li>
<li> If no other options will work, the image is described in surrounding paragraphs.</li>
</ul></li>
<li> Any text present in images exists in a text form outside of the image (this can be alt text, captions, or surrounding text.)</li>
</ul>
<h3 id="visualizations">Visualizations</h3>
<ul>
<li> All visualizations have an image description. Review the previous section, Images, for more information on how to add it.</li>
<li> Visualization descriptions include
<ul>
<li> The type of visualization (like bar chart, scatter plot, etc.)</li>
<li> Title</li>
<li> Axis labels and range</li>
<li> Key or legend</li>
<li> An explanation of the visualization’s significance to the notebook (like the trend, an outlier in the data, what the author learned from it, etc.)</li>
</ul></li>
<li> All visualizations have the following labels
<ul>
<li> Title</li>
<li> Labels on all axes</li>
<li> Key or legend (if relevant)</li>
</ul></li>
<li> All visualizations and their parts have enough color contrast to be legible. Remember that transparent colors have lower contrast than their opaque versions.</li>
<li> All visualizations convey information with more visual cues than color coding. Use text labels, patterns, or icons alongside color to achieve this.</li>
<li> All visualizations have an additional way for notebook readers to access the information. Linking to the original data, including a table of the data in the same notebook, or sonifying the plot are all options.</li>
</ul>
<h3 id="text">Text</h3>
<ul>
<li> All link text is descriptive. It tells users where they will be taken if they open the link.</li>
<li> Use plain language wherever possible.</li>
<li> All acronyms are defined at least the first time they are used.</li>
<li> Field-specific/specialized terms are used when needed, but not excessively.</li>
<li> Text is broken into paragraphs and/or cells where relevant.</li>
<li> Text is in complete sentences where relevant.</li>
</ul>
<h3 id="code">Code</h3>
<ul>
<li> Code sections are introduced and explained before they appear in the notebook. This can be fulfilled with a heading in a prior Markdown cell, a sentence preceding it, or a code comment in the code section.</li>
<li> Code has explanatory comments (if relevant). This is most important for long sections of code.</li>
<li> If the author has control over the syntax highlighting theme in the notebook, that theme has enough color contrast to be legible.</li>
<li> Code and code explanations focus on one task at a time. Unless comparison is the point of the notebook, only one method for completing the task is described at a time.</li>
</ul>
<h3 id="other-content">Other content</h3>
<p>This list is not exhaustive. If you are reviewing a notebook with content that you do not think fits any of these categories, keep in mind</p>
<ul>
<li>Text is flexible. Whether it is in the document or linked out, text can be read visually, be read audibly, be magnified, or be translated to another language. Having a text alternative is a good back up plan.</li>
<li>Having enough color contrast is required on almost all visual content.</li>
</ul>
<h3 id="videos">Videos</h3>
<ul>
<li> All videos have titles in the player or in the text before them.</li>
<li> All videos have captions/subtitles. This can include visual information descriptions if relevant.</li>
<li> All videos have transcripts. This can include visual information descriptions if relevant.</li>
<li> All video players have buttons with labels. This can be a persistent label or appear when hovered.</li>
<li> All video players have buttons with enough color contrast.</li>
<li> No videos have flashing images at more than three frames per second.</li>
</ul>
<h3 id="sonifications">Sonifications</h3>
<ul>
<li> Sonifications include a key explaining the mapping of data to sound. A written description can be used to convey this information.</li>
<li> Sonification outputs reference the method that generated the sonification. This can be done in a code cell or with a link to the file used to generate the sonification.</li>
<li> Audio players include basic listening controls for starting, pausing, volume, and speed.</li>
<li> All audio players have buttons with labels. This can be a persistent label or appear when hovered.</li>
<li> All audio players have buttons with enough color contrast.</li>
</ul>
<h3 id="interactive-widgets">Interactive Widgets</h3>
<p>The accessibility of interactive widgets varies greatly depending how they are included in the notebook. Review beyond this checklist may be needed.</p>
<ul>
<li> All interactive widgets with visual controls have labels. This can be a persistent label or appear when hovered.</li>
<li> All interactive widgets with visual controls have enough color contrast.</li>
<li> All interactive widgets have a summary of what they are and what they do in the surrounding text.</li>
<li> If an interactive widget’s contents are needed to understand the rest of the notebook, the widget either needs to be tested further or have that content fully represented not as a widget elsewhere in the notebook.</li>
</ul>

</div>

</section>

</div>