The Happiest Notebooks on Earth

There was a human named Joel Grus (@joelgrus), who did not like notebooks.

1. Hidden state and out-of-order execution
2. Notebooks are difficult for beginners
3. Notebooks encourage bad habits
4. Notebooks discourage modularity and testing
5. Jupyter’s autocomplete, linting, and way of looking up the help are awkward

6. Notebooks encourage bad processes
7. Notebooks hinder reproducible + extensible science
8. Notebooks make it hard to copy and paste into Slack/Github issues
9. Errors will always halt execution
10. Notebooks make it easy to teach poorly
11. Notebooks make it hard to teach well

There was another human named Jeremy Howard (@jeremyphoward), who actually did like notebooks.

A fair post-ac data scientist turned product manager was knitting notebooks to her heart’s desire

“We keep moving forward, opening up new doors and doing new things, because we’re curious. And curiosity keeps leading us down new paths. We’re always exploring and experimenting. We call Imagineering the blending of creative imagination with technical know-how.”
— Walt Disney

Mike Bostock:

“an interactive, editable document defined by code. It’s a computer program, but one that’s designed to be easier to read and write by humans.”

Martin Fowler:

“A computational notebook is an environment for writing a prose document that allows the author to embed code which can be easily executed with the results also incorporated into the document.”

1. Jupyter notebooks are notebooks. Jupyter is the product.
2. Observable notebooks are notebooks. Observable is the product.
3. Quarto and R Markdown notebooks are plain text documents. Two modes:

   • Notebook mode

   • Batch mode

Problem: Walt Disney found it jarring to see characters out of place. It breaks the suspension of reality.

Solution: Disney built the utilidor system — a system of some of the world’s largest utility tunnels

An intricate web of tunnels lies underneath the park, enabling characters to navigate to their respective “worlds” without ever appearing out of world or duplicative.

Less magic, more plain text logic

1. Configuration settings - often YAML in the document header or an external file - preferably define own variables
2. Outsource a script or document
3. Reuse code chunks in different places
4. Conditional evaluation of code

An example

Problem: Being at Disney World needs to be an immersive, memorable experience.

Solution: Disney built the smellitizer system — a system that blows air across scented substances to make the air smell a certain (ideally good) way.

Have you ever seen a notebook with…

1. No meaningful headings (or worse, cute or peppy ones)
2. No meaningful heading hierarchy
3. No navigation
4. No description of the data
5. No logical order

“Information foraging explains how users behave on the web and why they click certain links and not others.

Information scent can be used to analyze how people assess a link and the page context surrounding the link to judge what’s on the other end of the link.”

1. Add a clickable table of contents 📌
2. Add useful headings
   • Aim for H2 and H3 levels only
   • Use sentence case
3. Limit to five or six H2 sections max if you can
4. Have a topic sentence
5. Describe your data (5w+1H)
6. Lay things out in a logical order
   • Beginning > middle > end
   • Logical != chronological

Problem: When a single detail is wrong, you lose the experience and the magic.

Solution: Reduce the chances of losing the magic.

Examples:

1. You cannot buy gum

2. Official no-fly zone

3. Always within 30 steps of a trash can

1. Easy styling
   • Authors want fonts & colors!
   • Readers want fonts & colors!
2. Easy layouts
   • Basic grid with rows/columns
3. Easy show/hide code and results in output
4. Easy “run from the top” mode
5. Easy way to skip or freeze a code chunk

1. Version control
2. Export/download source file
3. Save all plots as image files
4. Extract all of my code into a script
5. Reproducible environments

Problem: Making something shareable makes it more memorable.

Solution: Make it easier to share.

Examples:

“The concrete—a brainchild of Disney and Kodak—creates more vivid photographs…and also makes the green grass appear greener.”

“[Cinderella’s] castle faces south, meaning the sun is never directly behind it. It’s (almost) impossible to take a bad photo of yourself in front of Cinderella’s Castle.”

Authors should be able to:

1. Quickly share incomplete thoughts (with errors in code!)

2. Time travel to different versions (with output!)

3. Stash bits of code out of sight (with utilidors!)

4. Annotate easily what to look at and what not to look at 🚥

“We’re on the brink of adventure, children. Don’t spoil it with questions.”
– Mary Poppins

Don’t touch that

it’s my emotional support notebook

1. Useful to record my code + thought process

2. Useful to get feedback from others

3. Useful to get help getting unstuck

4. Useful to help others get unstuck

5. Useful to teach with

6. Useful to learn with

7. Useful to collaborate with

8. Useful to publish work for my career

9. Useful to debug with (see reprex)

10. Useful to iterate on code with

• Tom Mock

• Allison Horst

• Rich Iannone

• JJ Allaire

• Charles Teague

• Observable Insight 2022 conference organizers

• AGU Notebooks Now! Initiative and support from the Sloan Foundation

• CANSSI and Rohan Alexander for this opportunity