Select text to annotate, Click play in YouTube to begin
00:00:02
Colaroid: a literate programming approach for authoring explorable multi-stage tutorials. This is a joint work by April Wang, Andrew Head, Ashley Zhang, Steve Oney, and Christopher Brooks. Multi-stage programming tutorials are key learning resources for programmers, using progressive incremental steps to teach them how to build larger software systems.
00:00:29
In practice, it is time-consuming for authors to create these tutorials and explain in full detail about each stage. Providing such full details is essential for readers to follow the process. Recently, computational notebooks have been widely used for creating rich descriptive documents about code.
00:00:53
Notebooks allow authors to blend programming instructions with annotations of the code. Such notebooks have been used by data scientists to create code tutorials. They support a kind of exploration and tinkering that is central to “learning by doing”. Because in a computational notebook, a code cell can be modified and executed, allowing
00:01:19
readers to explore how changes to the code influence the results. However, not all types of programming tasks are supported by the structure of computational notebook. Let’s take a look at this tutorial. Let’s say that we want to write a tutorial on object-oriented programming. We may start by define a dog class.
00:01:44
And then we decide to update the dog class with an init method. And we may also add a line above the init method to define a class attribute. Note that the granularity of the changes do not allow the code to be executed piecewise. As compared to a data modeling process where the changes can be executed in individual
00:02:08
units. Moreover, in authentic practice, these changes may take place between various code assets. The implementation of a single feature might be split across many places in the code and difficult to isolate into a single cell. As a result, tutorial authors often need to manually curate these steps from their coding
00:02:33
environment into a static text document. It is a tedious process for learners as well to follow these static text tutorials and reproduce the process in their local coding environment. What if we can leverage the benefits of computational notebooks to help programmers document incremental code construction for a broader set of programming tasks?
00:02:58
In particular, we want to bridge the gap between the authentic computing environment and the tutorial editing environment. allowing authors to capture their authentic practice of code construction process and make it into a narrative; For the other way around, allowing learners to “load” the process in their local computing environment from a tutorial.
00:03:23
We propose the idea of taking snapshots of code base and allowing users to annotate them and weave them into a narrative. The system name Colaroid is a variation of the camera Polaroid – as if where people take snapshots of their life moments and write thoughts and annotations on them. We implemented and tested Colaroid in the context of web programming, but its design
00:03:49
could be easily adapted and expanded to more languages and paradigms. We implemented Colaroid as an extension for Visual Studio Code, which is one of the most widely used IDEs. This helps optimize the authoring experience by allowing authors to write a tutorial while staying within their authentic development context.
00:04:14
This also allows the tutorial editor and the main code editor to interact with each other, as we will expand later. A Colaroid cell represents the historical state of the programming process. Every cell contains three components to make the historical state more understandable for readers: a text area to describe the explanations and rationales of the code in this state,
00:04:39
a code preview area showing the state of the code and highlighting the changes from the previous state, and an output area where the code in this state is rendered as a live HTML preview. Colaroid optimizes the authoring experience by allowing the authors to write these tutorials while staying within their authentic development context, capturing the context and highlighting
00:05:08
the changes with minimal effort, and enabling rich editing and styling on the tutorials. Colaroid automatically tracks the changes across multiple project files and displays the code preview and the output preview under the explanations. In this way, the authors don’t need to worry about how to communicate and present the process,
00:05:34
and thus can focus on providing better quality explanations of the processes. On the other side, the impact of code changes on the output might be not straightforward to observe. To reduce the effort of writing explanations on the expected behaviors, Colaroid allows authors to record interactions on the HTML preview that can be replayed by the tutorial
00:06:01
learners. When learners are interested in a particular step and would like to explore it by tweaking the code, they can load a particular cell into their main code editor. This will restore the historical state of the programming process on the learners’ side. Colaroid also supports various post-editings for authors to polish their initial draft,
00:06:25
including editing text explanations, editing code, and annotating outputs. For editing code, they can do so by loading a step into the main code editor, making changes, and having the changes reflected in that step and any follow-up steps. After creating the tutorial, authors can share the entire project folder with learners so
00:06:48
that they can open the tutorial in their own code editors. Colaroid works particularly effectively with cloud platforms like GitHub Codespace. When distributing tutorials through GitHub repository, learners can open the tutorial in an online VS Code Editor with Colaroid pre-configured. This makes tutorials easier to use and share among a broader audience.
00:07:14
Our vision in long term is to reimagine the GitHub code repositories with rich, live, and explorable documentation to demonstrate the stories behind the programming process, making it not only a platform for sharing and collaboration, but also for learning authentic practices. To evaluate how Colaroid supports documenting incremental code construction, we designed
00:07:40
two studies to investigate the authoring experience and the reading experience. To evaluate the authoring experience, we recruited instructors to create web programming tutorials from given topics using Colaroid. For the authoring experience, participants found Colaroid easier to use because they don’t need to handle the process manually for presenting the context of the code changes.
00:08:07
Participants also made comments about how video tutorials are hard to edit if they make a mistake. To further investigate the benefit of the Colaroid narrative in communicating the code construction process, we deployed Colaroid tutorials in a web programming workshop where students learned new programming concepts through project-based examples and applied them to a different context.
00:08:32
The web programming workshop teaches HTML5 games, using the flappy bird as an example. And students need to apply the techniques in a dinosaur game. Our study used a within-subjects design where participants were given the Colaroid tutorial and one of the traditional tutorials. We used GitHub Codespaces for participants to access tutorials.
00:08:56
All three types of tutorials are displayed side by side with the main code editor. From learners’ perspective, they found Colaroid tutorials easier to follow along with compared to video tutorials. They can skip to the key steps that they are interested in and learn at their own pace. Compared to article tutorials, Colaroid tutorials are more engaging because they can run and
00:09:21
tinker around with the codebase to see how it works. It also provides a more precise context. For example, some participants were confused about where to locate the newly added code in article tutorials. Colaroid is tailored specifically for web programming tutorials. Colaroid can also be easily extended to support other programming tasks.
00:09:45
Here we show a variety of tutorials created by Colaroid: animation, game, and data visualization. That’s the end of the talk. If you are interested in learning more details, please read our paper.
End of transcript