Table of Contents
For years, the standard way of teaching developers to use an API or library has been documentation: pages of function signatures, parameter tables, and reference lists. While these are necessary for completeness, they are often the least effective way to help someone actually start using a tool.
A better approach exists: notebooks. Instead of static documentation, provide an interactive notebook that allows developers to learn by doing.
Why Documentation Alone Doesn’t Work #
Documentation is usually written with the assumption that readers are patient, structured learners who want to absorb abstract details before applying them. In practice, most developers are:
- Goal-driven – They want to solve a problem now, not study an entire API surface.
- Context-limited – They rarely read end-to-end. Instead, they jump in, skim, and test.
- Experiment-oriented – They learn fastest by trying code and seeing immediate results.
Traditional docs create a gap between theory and practice. Developers end up copying incomplete snippets, guessing at missing details, and debugging before they even start.
Why Notebooks Win #
Notebooks collapse the gap between explanation and execution. They combine prose, code, and output into a single environment where learning is active rather than passive.
Here are the key advantages:
1. Interactive Learning #
Developers can modify parameters, rerun cells, and instantly see outcomes. This accelerates understanding and builds confidence far faster than reading abstract descriptions.
2. Immediate Feedback Loop #
In traditional documentation, a mistake means flipping back and forth between pages to figure out what went wrong. In a notebook, errors surface in real time, in context, making the learning process smoother.
3. Concrete Before Abstract #
People retain knowledge better when they start with a working example and generalize outward. Notebooks emphasize showing first, then explaining, which matches how humans learn.
4. Self-Contained Environment #
A notebook bundles narrative, code, and runtime context. Developers don’t waste time setting up scaffolding, finding sample data, or guessing configurations. Everything they need to succeed is in one place.
5. Explorability #
Instead of being a passive reader, the developer becomes an active explorer. They can test edge cases, try variations, and apply the library to their own workflows immediately.
6. Bridging Documentation and Education #
Documentation answers “What does this API provide?” Education answers “How do I use this to solve my problem?” A notebook does both simultaneously.
Beyond Reference: Shaping the Learning Experience #
This doesn’t mean reference documentation should disappear. It still serves as a comprehensive catalog. But the entry point into any library should be a notebook, not a static doc.
- Docs are for completeness.
- Notebooks are for understanding.
By leading with notebooks, you meet developers where they are: eager to build, test, and learn through interaction.
The Shift in Mental Model #
Think about the difference:
- Documentation is reading about a tool.
- A notebook is using the tool immediately.
For developers, that shift isn’t cosmetic—it transforms learning from a frustrating, time-consuming process into a direct, intuitive one.
If you want your users to truly adopt your tool, give them something they can run, tweak, and learn from directly.
Don’t just document your APIs. Notebook them.
Why Scribbler Is Best for This #
Notebooks exist in many forms, but Scribbler is uniquely positioned for API and library learning. Unlike heavy scientific notebook tools, Scribbler runs directly in JavaScript, in the same ecosystem where most APIs and libraries already live. That means no context-switching, no complex environment setup, and no heavyweight dependencies. Developers can open a Scribbler notebook and immediately interact with the exact tools they’re trying to learn. Its lightweight, web-first design makes sharing effortless: a notebook isn’t just a tutorial, it’s a live, portable playground that lowers the barrier for exploration and accelerates adoption.