Executable books emphasize understanding pre-existing code, not writing new code

At least as usually conceived, Executable books package and present the code discussed by their prose. Readers might be asked to extend that code in exercises, but executable books present code an object created by the author to be explored. The prose aims to help students read and understand the code. An interesting alternate approach is to consider executable book-like mediums which frame the code as something predominantly written by the reader.

Such a book would be more like The Incredible Machine than a Rube Goldberg picture book: it might present Fine-grained task progressions as cognitive scaffolding and relevant information along the way. The reader’s doing the execution, but that execution is highly structured by the author: an Enacted experience. Related: What might it mean to situate games like Shenzhen I/O inside pro environments like an IDE?. A concrete example, in design: Figma’s copy and paste playground situates instructional media inside the context of use

Another example; Pavel Panchekha is working on a book on how to build a web browser. He explicitly doesn’t want the book structured as a normal executable book—code samples easily runnable and remixable—because he wants readers to build their own web browsers.

An executable book approach (like a notebook) is good for understanding fixed code. You can run it piece by piece, read commentary, and see each piece highlighted as the text describes it. But that encourages a mode of interaction where you read the code, not write it. Perhaps it is too much to ask that the average reader will actually write a web browser, but at the very least I make my own students do so! A similar concern for self-explaining code, where the browser records some sort of rich log of its own activities and lets you explore it. Again it’s about exploring a fixed code base, whereas the real goal of the book is not so much explaining how a browser works as convincing the reader that they could write one.


Q. Why doesn’t Pavel think the typical conception of an executable book would suit his book on browser engineering?
A. Executable books are mostly about reading and understanding pre-existing code; he wants readers to actually write a browser.

Q. How do the “code listings” in games like Shenzhen I/O and The Incredible Machine differ from those in typical executable books?
A. They’re intentionally incomplete: players are meant to fill in the blanks.


References

Conversation with Pavel Panchekha, 2020-09-01: Re: Making my book a timeful text

Last updated 2023-07-13.