Composing Flexibly-Organized Step-by-Step Tutorials from Linked Source Code, Snippets, and Outputs

Programming tutorials are a pervasive and flexible teaching medium. Good tutorials interleave code snippets with text and illustrative outputs and and build up a target program in multiple steps. We interviewed 12 tutorial authors and performed a content analysis of 200 tutorials to learn about their structure and the challenges authors face when creating them. One challenge is that authors have to manage a complex workspace with the program, snippets taken from that program, prose explanation of snippets, and outputs generated by the program. Changing any one of these requires updating many other items.

00:36 - We introduce Torii, a novel tutorial editor designed to address this challenge. Changes to the code in one location are propagated to the code everywhere else it appears and program outputs are automatically updated. To keep outputs consistent, Torii introduces a new execution model in which snippets are executed in the order they appear in a complete source program, which can be different from the order they appear in the tutorial. This gives authors the freedom to present snippets in any order they feel is best for the tutorial, while letting them embed outputs that can be updated live as the code changes. Let’s say I’m writing a tutorial introducing object-oriented programming in Python.

01:11 - I have a source program, and I want to describe how it gets built up step-by-step. With Torii, I do this by adding snippets, outputs, and explanations. I add snippets by selecting code from the source program and clicking “Add Snippet”. The added snippet is automatically linked back to the source program. Edits to the program propagate to the snippet and vice versa. I add text to describe the code in the snippet. Then I add some more snippets, and then an output. A conventional notebook wouldn’t run this code correctly. In this case, I wanted to show the instantiation of an object first to ground why I would want to create a class before declaring that class. To generate outputs, Torii infers how snippets are supposed to be composed into a program by remembering their original ordering in the source program and using this to create and run a program snapshot.

02:01 - I can view the snapshots Torii is building by opening the snapshot view for any snippet. Because the outputs update live, I can check that the code runs as intended at each stage, even as I make changes to the code. These outputs are key for me to check my work when I want to make changes to a long tutorial. Torii continues to keep snippets and outputs consistent, even as I show code in more than one snippet, split code into syntactically incomplete blocks, and hide lines of code I don’t want the reader to see. This lets me as an author show code just in the way I want while making sure that the outputs can indeed be reproduced from the snippets shown.

02:43 - If I want to change code for just a part of the tutorial, I can pick a snippet, unsync it with the previous snippets, and make my change. When I’m done, I can publish a Torii document by exporting a Markdown file with embedded step-by-step snapshots of the program. .