Storyteller: A New Medium For Guiding Others Through Code

#learning #tutorial #vscode #showdev

As a computer science instructor, I have long wished that there was a better way to guide others through my code. When I was first learning to program I was a big fan of traditional programming books. I have shelves and shelves of 800+ page books covering different programming languages and technologies. I have known for a while now that most learners today don't share my love of big thick books, and to be honest, I rarely read those books in their entirety. Those big books often had a lot more exposition about the code than was probably needed. As a book buyer I wanted to make sure that I was getting my money's worth so the thicker they were, the better. It is much more common these days for learners to consume blog based tutorials and videos.

Blogs and Videos

Blog-style tutorials mix code and the explanation of the code in a top-to-bottom fashion. Scrolling through these feels familiar and one can copy and paste with ease. However, linking the explanation of the code and the code itself has always been less than ideal. Often I find myself jumping around the blog post wishing I could see the entire code example while working through the explanation. Instead, I am only able to see small parts of the code and it is challenging to see how those parts relate to other parts.

Video tutorials are very popular these days. They solve some of the problems associated with blog-style tutorials. A viewer can focus on the code that is being written while listening to the explanation. However, videos have some problems too.

Viewing videos

From the perspective of the viewer, videos are not useful as a copy and paste source or a code reference. More importantly, though, they discourage the viewer from taking their time and reflecting on the material. Often when I am viewing a video tutorial I don't pause and let concepts sink in before the video moves on. Yes, I could be more disciplined and pause and rewind more often but usually I don't. The video slider is not a great search tool!

I have the same problem with audio books. I only listen to very light fiction or biography audio books because if I miss something in the first listen it is usually too hard to go back and find it. It is easier to let the audio play on. If there is a book I really want to understand I get a hard copy and read it the old fashioned way.

Making videos

From the perspective of the video creator, it is clear that not all code being developed is interesting to watch. Some of it is not really worth showing the viewer. Not all video creators can keep the narrative interesting the whole time too. I know I struggle with the 'performance' aspect of making videos (you won't find me coding on Twitch anytime soon). Many times after I am done making a video, as I review it, I wish I had mentioned something that I forgot. It is hard to go back and edit the video without scrapping it and starting over.

Storyteller

I have been working on a new medium used just for guiding viewers through code examples. It combines the best of books, blog posts, and videos. This new medium allows a developer to write code using a top-notch editor (Visual Studio Code) and then replay the development of that code in the browser. The author can add comments at important points in the evolution of the code and publish the resulting code 'playback' on a web server. The comments can include text, hand drawn pictures, screenshots, and audios/videos. The tool is called Storyteller.

Here are a few examples of a 'playback':
Adding a Border to a Picture (Python)
Enlarging a Picture (Python)
Functions with parameters (C++)

These work best on a big screen. If you are viewing a playback on a small screen you can view it in 'blog' mode (there is button in the top right to switch from 'code' mode to 'blog' mode).

Here is a demo of how to create and view a playback.

I have created groups of these guided code walk-throughs to help me teach different topics to my students. These are all free and hosted on GitHub:

Sometimes I assign these as readings to my class instead of using expensive textbooks. It is a lot easier for me to write several programs than it is to find a perfect textbook (or to write my own).

I also use them for in-class demos instead of writing code live. This makes code demos flow much faster and smoother. If I make an interesting mistake while preparing the code I can still highlight it with a comment. If I make an uninteresting or embarrassing mistake I can just ignore it and the students likely will not see it.

The advantages of code playbacks:

The primary focus is on the code. It is always visible and easy to navigate.
Since the code is so accessible the explanation of it tends to be shorter and more concise.
I can review the code several times and add/edit comments each time I go through it. I don't have to give a perfect performance. I get multiple chances to 'get it right'.
Comment points highlight when the author wants the viewer to take a moment to really think about the code and reflect on it. The playback only moves forward when the viewer is ready.
The code mentioned in a comment can be highlighted so the viewer knows exactly where they should be looking.
The code can be downloaded at any point in the playback. Then a viewer can run it, change it, and add to it.
The tool is a language independent editor plug-in and can be used to describe programs in any language.
Viewers only need a web browser to go through a playback.
Comments can include whiteboard style drawings, screenshots, videos of running code, or use videos in place of a textual explanation.

Let me know what you think!

Links

If you would like to create your own playbacks the VS Code extension is called 'Storyteller'. You can find it here. The tool is free and open source.

The project repo can be found here. Here is some documentation. If you'd like some help getting started feel free to reach out to me.

My most recent collections of playbacks can be found here. I am currently using GitHub Pages to host them.

If you'd like to stay informed on the development of the tool or know when I release new content you can follow me on twitter @markm208 or follow the tool directly @StorytellerCode.