JupyterHub best practices

Last updated: February 14, 2024
Audience: InstructorsIT Staff / Technical

The following best practices come from the JupyterHub pilot studies.

Instructor Prep

  • Instructors who were using JupyterHub for the first time relied on UW-IT’s standardized setup to get started. Although many instructors in this group had used Jupyter notebooks in previous courses, they relied on computer labs or students’ local environments as part of their teaching structure. With the adoption of JupyterHub, instructors were able to take advantage of the cloud environment, with some support from UW-IT. This format worked well for new adopters, as the JupyterHub setup provided a stable foundation for integrating Jupyter notebooks and ensured that all students had access to the same environment.
  • Experienced adopters crafted specific scripts that allowed them greater integrated control.

Course Content [nbgitpuller]

  • Synced repositories must be public, so be careful not to add any restricted or sensitive data.
  • Never commit the hidden directory “.ipynb_checkpoints” to your repository.
  • Never use manual git commands on the synced folder in notebook servers.
  • Be aware of the volume of data you’re syncing and avoid adding binaries or large data sets to your git repository if possible.
  • Nbgitpuller uses an automatic merging strategy to reconcile changes in the Git remote with any local changes your students have made in the same folder, which is usually seamless, however there is a bug with nbgitpuller when deleting files from the git repository: if a user also deletes the same files locally prior to their notebook syncing, it will prevent the notebook from starting and require intervention. We generally recommend that users don’t delete files in their synced directory unless they created the files.
  • Students cannot push changes they make on their notebooks back to the git repository.
  • Additional information available from the nbgitpuller documentation.

Feedback & Grading

  • Instructors may want to choose their feedback and grading tools based on individual course learning objectives. Common solutions include Canvas integration, GitHub, and syncing student-instructor directories.
  • With the creation of rubrics and answer keys, teaching assistants can provide feedback on assignments similar in quality to an instructor with some instructor oversight.

Class Structure

  • When developing the course, keep it simple. List course objectives and explore the necessary tools and datasets. Identify which sections of data will allow students to effectively learn a specific tool and/or specific content.
  • If the course expects an existing foundational knowledge of Python, instructors may want to cover basic coding concepts at the start of the course, but quickly build upon that and shift toward content instruction.
  • Instructors should anticipate needs for support and resources while students ramp up the necessary Python skills to succeed. Many students will come to classes with backgrounds in other coding languages (e.g., GIS, MATLAB, R, etc.). Students will require time to transition to Python and newcomers will need to learn how to efficiently manage their notebooks (e.g., key strokes, code and formulae formatting).
  • Instructors who adopted an asynchronous structure felt that learning with the notebooks worked best when students “played” with the code independently and when students were able to discuss and troubleshoot issues between themselves outside of class time. These instructors covered content and code instructions in pre-recorded lectures, and strategically used class time to facilitate breakout rooms for students to discuss code problems or troubleshoot issues together through their notebooks.
  • Instructors also used class time as office hours so students could ask questions directly, which provided opportunities for personal attention and individualized instruction.
  • Consider how to structure Jupyter notebooks for assignments in order to maximize their potential as a teaching and learning tool. Two options: (a) instructor-generated notebooks with partial code that students fill out as part of assignments, or (b) notebooks that have all the code that students can run and explore, with open-ended problems at the end.
  • Consider when students will receive access to readings, labs, and solutions. Given the dynamic learning environment of Jupyter, providing students access to labs and solutions some days prior to class periods can help maximize time spent together. When students are able to preview labs before class time, they can ask the instructor, a TA, or their peers more targeted and intentional questions.
  • The need for a discussion forum was dependent on the size of the course. Several of the pilot courses had fewer than 15 students enrolled and the instructors found email sufficient to coordinate discussion and interactive activities. For larger classes with more than 15 students, instructors used Canvas Discussion boards and Slack to foster student discussion.
  • One department took advantage of its course-specific Slack channels for asynchronous discussions.