Interactive Notebook Demo

Overview

A demo notebook does two jobs at once, and must do both:

• Orient — it doubles as semi-interactive documentation for a feature. Read top to bottom, it should leave the reader understanding the motivating problem, the design, the mechanism, and the data flow — the narrative layer over the code.
• Interact — a reader can run one operation, read the real output, edit a literal, and re-run, building hands-on understanding by poking at it. The cells are the examples; git holds the original, so they can change anything and revert.

The orientation is what to teach; the interaction is how to teach it. A notebook that interacts beautifully but explains nothing is a toy; one that explains but only runs as opaque blocks is a slideshow. Clear both bars.

Two failure modes make a notebook performative (a script that happens to have cell markers) rather than interactive: