A Newcomers Guide to Storyteller


by Mark Mahoney


This 'guide' of playbacks is intended for people who wish to contribute to the open source project called, Storyteller. Storyteller allows programmers to show and tell the story of how their code evolved. With some additional functionality I hope it can also be used as a full featured version control system but whether that is possible is still up in the air. Modern version control systems like Git are snapshot based. Developers 'check in' their code at what they believe are important milestones. I call this the 'snapshot' based approach. There are some interesting things that happen in between commits that often get lost in commit messages. Perhaps worse, there are some longer scale stories that are missed because there is not a good place to write them down. Commit messages are not targeted or focused on individual code changes which makes it difficult to tell a story with them alone. Even if a developer commits regularly in very small, fine grained chunks the plain text that Git captures for commit messages is not an ideal medium for telling a compelling story. While programming I am often drawing pictures or imagining pictures in my head. Often, these visuals do more to tell the story than the code itself. We need more powerful means to express our ideas than just code and commit messages. As a developer I want to be able to show others the pictures that helped me when writing the code. Sites like GitHub go a long way towards helping make Git better at storytelling but I am looking to make a version control system that has storytelling baked into its core. Storyteller aims to be more of a 'moving picture' medium than a 'snapshot' based one. Git was designed to be independent of any text editor. It is only active when one issues a Git command. Storyteller works in the text editor to record programmer keystrokes and file operations so that they can be replayed in their entirety along with a narrative from the author. Integrating a version control system with an editor loses some flexibility but I think it is worth exploring if the advantages outweigh the negatives. Git is very fast and efficient. While I admire both of those characteristics neither of them were my primary goals. Creating narratives is at the heart of Storyteller. In order to accomplish this it records keystrokes and file operations provided by an editor and stores them as a sequential collection of programming 'events'. A playback simply marches through these events. An author can attach comments to any of these events. A comment can include text, hand drawn pictures, screenshots, audio recordings, video recordings, and code highlights to focus the reader's attention on the star of the show, the code! Although one can watch every keystroke get animated in a playback most people (so far anyway) have preferred to move through the code at comment points only. This seems to be the fastest and most valuable way of watching playbacks. Storyteller works with Visual Studio Code as an extension. The bulk of the functionality is written in javascript and can run independently for the VS Code extension as a node app (contact me if you'd like help writing a plugin for a different editor). I have been using Storyteller for a couple of years in the CS courses that I teach as a textbook replacement (https://ourcodestories.com/markm208/Playlist/All). It can also be used by others to create programming tutorials, books, or semi-live demos. I would like to see it be used as a code review prep tool, a tool for newcomers to a system, and of course a version control system. It may prove impossible to create a 'moving picture' based version control system that is powerful enough to satisfy the needs of a modern developer. This is what I am exploring with this project. I wish I could say for sure that we will get there but I honestly don't know what will happen in the future. In order to help you contribute to this system let me give you a guided code walkthrough of the system up to this point. If you have comments or would like to contact me you can reach me at mmahoney@carthage.edu.