4 Practical Suggestions for Using Jupyter Notebooks in Tutorials

Who is this for?

This post compiles suggestions for anyone using Jupyter to do a tutorial — that is, a short (a few minutes, an hour, a day) stand-alone lesson on some topic. Suggestions may apply to longer lessons but this is mostly for people who:

• Work in science/tech/etc. but who have little to no experience teaching tutorials (there are important differences from teaching a formal class!)
• Are already planning on teaching the tutorial in Jupyter (not trying to convince you about why you should/shouldn’t use Jupyter — I think it’s great in many, but not all cases)
• Will be presenting a tutorial in-person (although many tips will apply to
  online tutorials)
• Want their tutorial to work, be reused, and improved upon
• Have at least a basic knowledge of Jupyter notebooks/lab (scroll down to the resources section if you have never used notebooks before)
• Don’t have a lot of time

I hope that even if your tutorial is written and you are on a plane traveling to deliver it, this post will give you some pointers you can apply right now.

Why write this post?

Having seen tutorials (including some I’ve written myself) that weren’t as
effective as they could be, I wanted to save you, me, and others. If you have
taken a workshop using Jupyter, then you might understand the frustration of signing up for a tutorial only to be confronted with a notebook that didn’t work because of dependencies. Even worse are tutorials which are in reality “scroll-strolls” through un-commented Python scripts. The notebooks end in the .ipynb extension but contain code arbitrarily chopped up into cells, no markdown cells, and no usage of the notebook’s interactive properties (definitely wrote this after attending my first JupyterCon).

Tutorials with these shortcomings don’t fail because the people writing them aren’t experts in their topic. Tutorials with Jupyter notebooks fail because they don’t use the notebook’s greatest strength — communicating ideas.

It’s unsurprising that many science and tech experts don’t have formal
backgrounds in education. Software and Data Carpentry (The Carpentries) have done an excellent job getting the best practices of teaching into the hands of this crowd (see resources at the end of this page). Still, if you don’t have access or time for their two-day instructor training course, I’ve condensed ideas from the Carpentries course and some other related content into a few points you can use.

Suggestion 1: Define your audience

In a nutshell: Make some sensible assumptions about who your learners are.
Use every bit of data you can gather about your audience and go from there.

This suggestion applies to any tutorial, and is the starting point for thinking
about your notebook content. Here is a breakdown of questions you should ask yourself and some immediate suggestions to consider:

Ask yourself: Who is the learner that will be attending my tutorial?

Suggestion 2: Make your goals clear

In a nutshell: Decide on learning goals you think your learners can achieve (given the assumptions in suggestion 1). Make these goals explicit topics that organize your notebook’s layout.

What are the one, two, or three most important things you want to teach? If you are aiming for more than 3 main ideas, think hard about whether they will fit in a single tutorial. Your learners need to prioritize and so do you. Insist on getting a description of your tutorial and its objectives to learners ahead of time. This will make you accountable to do your best in achieving the stated objectives. It also allows the learners to decide if this tutorial will be worth their time.

Form your learning objectives

Here are some tips for writing good objectives. Main ideas might be broken down into 2–3 learning objectives but you will have to decide on what you can cover. Objectives should be:

• Action oriented: “learners will be able to…”, “learners will understand…”
  — If you are interested, Bloom’s taxonomy is the well-examined foundation for this style
• Should be testable: Can you (or more importantly learners) tell if an objective has been successfully completed?
  — Although you probably won’t give a final exam to your learners, you should plan to ask questions that help learners evaluate if they are understanding your material
• Should be Achievable: Can your assumed learner succeed given your constraints (e.g. your time, their assumed prior knowledge, etc.)?
  — Don’t promise learners will master materials that may take years to learn. Be realistic about what you can teach, and what your learners can absorb

Once you have your objectives, go back through your materials and ask if you
have achieved these objectives. Would the you of one, two, or five years ago be able to get the points you are trying to make? Is it possible your tutorial is filled with assumptions you didn’t see because of expert blind spot? Remember it’s OK (in fact better) to let learners know what will take more time to learn.

Use your learning objectives to outline your notebook

Use headings for the concepts your notebook lays out. If your topics are
complex, divide your content into multiple notebooks. This spares learners from scrolling and getting lost. It will also make it easier to organize your materials.

Ask yourself: What could a learner do to show they can understand, apply, and modify the knowledge you are passing on? Referring back to Bloom’s, you can’t expect learners to make magic leaps between the content you managed to teach and the more complex applications of that information you assume they can now intuit their way towards.

Suggestion 3: Make the notebook and the learners do their share of the work

In a nutshell: A notebook is interactive — give learners useful activities to do. Learners are inquisitive — use notebook narrative to isolate and expose concepts that might otherwise be hidden.

Putting aside technological features (see suggestion 4), the strength of the notebook is to lay out code for effective communication. Rather than walk your audience through a script (where every line may be equally important) a notebook should draw the learner’s attention to what is conceptually important.

Let the notebook do its job

Provide some context — Make use of the markdown cells to include introductory material and state your learning objectives (suggestion 2). Make use of hyperlinks to other learning materials, or even include images and figures.

Prioritize concepts not code — Laying out code in a notebook should not be done in the same way you would write a script. Instead, ask the following questions as you are authoring the notebook:

• Where is my learner going to start when they try this on their own?
  — What will they need to install/import (on their own machine, outside of
  the tutorial session)? Will installs/setup be trivial for them (given their
  expected skill level)? Shall I include this in the tutorial or will I leave this out to keep a tighter scope?
• What is hard about the topic?
  — Where do I need to explain background science, math, etc. to keep my
  hypothetical audience following me?
• What is hard about the code?
  — What did I have to spend a lot of time figuring out? What steps are
  counter-intuitive? What syntax might be very specific to the libraries or
  the computing context I am using? Are the steps learners will want to
  customize obvious?

As you answer these questions, you’ll better discern where you need markdown cells to provide explanation and context. You absolutely don’t need to explain everything to the learner. Instead, do your best to cover as much as you think your audience needs. Experienced Python developers shouldn’t be tripped up by iterators, but first-timer trainees in machine learning might need to review statistical concepts.

Keep focused on your objectives — At any given moment, the knowledge you are communicating may switch focus between the code (here is how you do this) and the domain knowledge (here is why we are doing this) throughout the notebook.

• When code is the focus
  — Explain what is happening with the code and why
• When domain knowledge is the focus
  — Minimize the code. It’s OK if some blocks of code just need to be accepted by the learner without detailed explanation

Let the learner do their job

One way to define a successful tutorial is to encourage learners prove to
themselves they have understood the materials. Presumably, learners want to learn (although your motivation and enthusiasm can greatly affect this) so don’t be afraid to challenge them.

Ask questions and get feedback — Although a tutorial is not an exam you should include questions in your tutorial. If you don’t ask questions during tutorials, you literally have no way of knowing if people are getting what you are trying to teach them. A drowning person doesn’t necessarily flail their arms in the water, and lost learners may not look lost. The same goes for learners who have lost interest because they could not follow you. Some options for increasing feedback from learners include:

• Include markdown cells with questions/discussion topics and then TPS (Think-Pair-Share) — this is my favorite strategy for dealing with a quiet group, reluctant to answer questions.
  — Think: Ask your learners to think about their answer
  — Pair: Ask learners to pair up and discuss their answers
  — Share: Ask learners to share some of what they discussed
• Use Notebook extensions to include question/answer cells
  — The Exercise and Exercise2 extensions are easy ways to include questions and answers.

Make use of the play button — Interactivity is the point of the notebook. If we wanted to simply run all the cells at once, we should be scripting instead. Based on your learning objectives, and your answers to the prioritize concepts not code questions think about where you need your learners to stop, pause, think and answer a question, then have them run, manipulate, and re-run cells.

Ask yourself: Why is my content better presented in a notebook, vs. A script, or a documentation repository like ReadTheDocs?

Suggestion 4: Make your tutorial reproducible and extendible

In a nutshell: If your tutorial can’t work without you in the room you have a problem. Solutions can be basic (code on GitHub) or very easy to use for novice learners (Binder, Cloud, Docker).

Probably the most important thing about a notebook-based tutorial is that the
notebook works for every learner — don’t waste time having users install anything. We’re making a bet here that the focus of your tutorial is not about
installations (including how to install Jupyter) — a possible exception is when your tutorial is long enough to cover installation from scratch (helpful for those with little Linux/command line experience) or when installing something complex is the point of the tutorial. Here are some things you can do to make using your notebook (rather than installation troubleshooting) the focus. Assuming your notebook is well documented learners will find a way to overcome technology and installation problems; remember the value of an in-person tutorial is the face time spent with you, the science or tech expert.

Put your notebook in a public repository with a license — At a minimum, your notebook should be in a public repository (such as GitHub). This allows your users to submit issues (if you have time show them how — no need to make them learn git). Also have a license that allows others to reuse your notebook. Maybe you’ll even get a pull request!

Consider using Binder — Once your notebook is in a repository, you can use Binder to let users run the notebook at a click of a button. You can stage example data in your repo, and your dependencies can be included in a straightforward text file. This also keeps you honest about the goal of making your notebook run after the tutorial!

Make use of the cloud — In some cases, setting up a Jupyterhub is a good solution (perhaps you have large datasets than can’t be included in a repo. Maybe you want to give some post-workshop access). I have a sloppy but functional dockerhub image that I use in my teaching, and you can do a better job at getting something setup for your class. CyVerse now let’s you launch Jupyter lab/RStudio instances which you can pair with high-powered computing and data (full-disclosure, I work on that project). You can configure your dependencies in a Dockerfile, and your learners can launch and use your notebook in 2–3 minutes. The CyVerse resources are specialized for biologists so if that is your use case learn about their VICE resource (see also a webinar on VICE).

Ask yourself: What will make it difficult for someone to take my notebook and run it on their own system?

Bonus Suggestion: Know when not to to use a notebook

I said this post was not about convincing you to use Jupyter. I wanted to remind you I don’t think Jupyter is the solution for every teaching case. There is more than one discussion thread about some of the things people don’t like about teaching with Jupyter — that’s OK. Here are some reasons why you may not want to use Jupyter for your tutorial:

Your audience has a strong aversion to notebooks — Jupyter is usually used when narrative and ease-of-use is prioritized. For some programmers, there may be a strong preference to work in plain-text scripts/text editors or their preferred IDE. If you are not sure about your audience, talk to those who
might know them, or try to conduct a pre-workshop poll (assuming you have time to react to preferences). When you have little prior knowledge of your audience, a simple 4–5 question Google poll at the beginning of a tutorial can be very helpful (here is an example from a recent workshop).

You are teaching programming (sometimes) — Jupyter can be great for introductory programming. However, there are some features of Jupyter (hidden states, cell ordering, etc.) that may be tricky. Some of the concepts and practices of enterprise programming may get lost or confused with Jupyter and in those cases the platform may do more harm than good.

Other resources for teaching with Jupyter

• A whole e-book for teaching with Jupyter!
• The main Jupyter site — start here for your technology questions
• The Carpentries instructor training curriculum to improve your teaching skills
• Teaching tech together for specific tips on teaching programming
• Binder to make your notebooks reproducible
• CyVerse VICE if you are using Jupyter to teach biology. You may also consider using their free Atmosphere cloud
• Training in the life sciences? Join LifeSciTrainingSlack

Hope this was useful and please comment on what you agree/disagree with and share any resources I missed!