Explorable explorable explanations

2025-11-12 computer-aided research

A much cited essay by Bret Victor, “Explorable Explanations”, argues for supporting and encouraging active reading in communicating ideas. Explanatory text should thus be complemented by interactive visualizations and computational demonstrations, allowing the reader to actively engage with the ideas. If you haven’t read Victor’s essay yet, please do so now, and then come back here. It’s not very long. What I am going to discuss is a variation on Victor’s proposal, and I won’t repeat his well-presented arguments.

The starting point for my own work on this topic was the observation that scientific communication, traditionally centered around journal articles, is exactly of the kind that would benefit from more interactivity and potential for engagement, including critical engagement, as described by Victor. That observation has been made many times by many people in many contexts. Anyone who has worked with interactive data management or visualization tools on a computer sooner or later comes to the conclusion that we could do a lot better today than exchange information on printed pages (or their electronic equivalent, the PDF file). Many have proposed computational notebooks, such as the popular Jupyter notebooks, as a more interactive update to the traditional article. Some notebook-based tools, more notably Quarto, are even explicitly advertised as publishing technology. I have expressed my disagreement before, and proposed some ideas for improving on notebooks. Now is the time to follow up with a working prototype.

Bret Victor’s explorable explanations are a much more promising approach, in my opinion, because they focus on guiding the reader towards exploring the most salient ideas, rather than forcing them to follow the logic of a sequential computer program from top to bottom. Moreoever, their interactive elements are designed for non-destructive experimentation, whereas a notebook encourages its readers to explore by modifying the author’s work, and thus easily losing track of what the author’s had written initially.

However, Victor’s examples, implemented as Web pages embedding interactive components written in JavaScript, have some serious shortcomings as well when seen through the lens of scientific communication (which was not his use case). The most important one is the opacity of the interactive components. Consider his “digital filter” example. The interactive component is a great way to understand the relation between inputs, outputs, and filter parameters. But you can’t easily see the computations done behind the scenes. You have to trust the author to have implemented the equations governing the filter correctly in JavaScript code. Unless you are a seasoned Web developer, in which case you will look at the HTML source code in your navigator, go through the list of script files, find and look up filter.js, and figure out how that code works and how it relates to the equations it implements. For a more complex computation using canned library code, this approach becomes completely hopeless. Just like for a notebook, of course. Both notebooks and explorable explanations are shallow, meaning that they make a surface layer of computation very accessible but don’t provide access to the code that they build on.

For scientific communication, we need to take one more step. We need explorable explorable explanations. The explanation itself, including its interactive elements, must be explorable as well. The source code of all visualizations, animations, or interactive tools must be accessible in a straightforward way. Readers must be able to dig as far down into the software stack as they deem necessary for their understanding.

This has been the core objective of my HyperDoc project, which I have written about before. For an example of an explorable explanation in HyperDoc, see Micrograd, an explanation of neural networks built on top of an automatic differentiation engine. Unlike Bret Victor’s examples, an explorable explanation in HyperDoc is hypertext, i.e. it consists of smaller interlinked nodes. These nodes can be narratives, i.e. text with embedded images, tables, code, etc., like for example this one. But the hypertext nodes can also be code pages, such as this one, which is perfectly ordinary code written in Common Lisp (if you wonder about this somewhat unusual choice of programming language for scientific computing, see HyperDoc’s goals and values). Interactive tools are another kind of node, as for example this one, which lets you explore the impact of the two parameters of a synthetic dataset. Moreover, any piece of computed data can be a node in this hypertext as well, as for example this multi-layer perceptron (click on the individual neurons to see their parameters).

There is also something similar to a notebook: the playground. It is basically a text editor in which you can write code and comments, and execute one or several expressions by clicking the “Eval” button, or typing Shift-Enter. The result is then shown in a new pane to the right. As the author of the HyperDoc, I have provided initial playground code that serves as a guide for exploration. You can always go back to that code via the “Reset” button, but otherwise, your changes are persistent on your computer, so you can come back to it later. Unfortunately, code execution in the playground is disabled on the Web server, for security reasons: it would let anyone execute arbitrary code, potentially breaking the server, storing illicit material, run bitcoin mining code, etc. Until I get around to implementing a sandbox, you will have to install everything on your own machine to use the playground.

Another important feature of HyperDoc is alt-clicking to see “behind the scenes”, which usually means “see the source code”. On the multi-layer perceptron, alt-click the tab labelled “Layers” to see how the “Layers” view is implemented. You can also do that with the “Graph” tab for the “Graph” view, but that will show you a rather complicated piece of code, since getting Graphviz to arrange nodes exactly as you want can be a rather messy affair. Once you have a piece of code before your eyes, move the mouse cursor around. Whenever some code element is shown with a grey background when you hover over it, clicking on it will show you where it comes from. You can navigate the entire codebase in this way, including libraries. Symbols shown in bold are part of the Common Lisp standard. If you click on them, you get to the corresponding page in the language standard. There is a lot more you can usefully alt-click, so go ahead and play with it!

The relatively small hypertext nodes that are shown side-by-side as you navigate through the links support deep active exploration. When a narrative points to a dataset, for example, you can explore the dataset interactively while still having the explanation in the narrative in view. Note that you can also embed a dataset or a code snippet inside a narrative, if you consider that the best way to present your work. I do it for small code snippets in some places. But unlike with notebooks, or with Bret Victor’s explainable explanations, this is only one way to present things, and it’s neither the default nor the most straightforward way.

There is a second, less obvious advantage to structuring the presentation in terms of small freely interlinkable nodes: modularity, reusability, and comprehensibility of implementation. Web pages are usually written for a potentially large number of anonymous readers. Most of these readers engage only superficially with the material. Scientific communication is different. Readers are peers. They read my work and I read theirs. Author-reader relations are not always individually symmetric, of course, but overall, everyone is both author and reader. Providing straightforward access to all the code, nicely structured into small units, encourages readers to learn not only about your subject, but also learn from your coding and presentation techniques. Given favorable legal conditions, readers that stumble upon a nice visual presentation can copy the code and adapt it for their own use in their own work.

This explains the title of this post: I want explorable explanations to be meta-explorable. I want them to be convivial technology for scientific computing, rather than a technology controlled by a small group of experts. My current prototype doesn’t achieve that goal yet, for various reasons that I will discuss in a separate post, but I believe that it already shows that convivial scientific computing is not just a pipedream.