markm208

I am the author of the tutorial. I created a tool that captures keystrokes and file operations in a popular editor and allows them to be played back in a browser. The author can then add a narrative as the code evolves with text, pictures, and videos.

I have more 'books' on C++, python, SQL, web dev, dart/flutter, clojure, ruby, and more:

https://markm208.github.io/

I use these for the programming-focused cs courses that I teach instead of having the students buy bloated textbooks. The students prefer them to books (no surprise) and videos (somewhat surprising). The code is searchable and copy/pasteable so the students actually use it.

The tool is free and open.

I have struggled with the speed at which I can write code live in class. It is hard to do it fast enough to keep students interested. It is also difficult to show even moderately complex programs from start to finish.

I have created a tool that allows me to move quickly through my code where students can still see how the solution evolves. I can comment at interesting points in the development of the code and attach hand drawn pics and screenshots. Here are some examples:

https://ourcodestories.com/markm208/Playlist/All

(Click on the >> button to move from comment to comment. These work best on a big screen)

I show some of these in class before asking the students to work on a related problem. I require the students to view the rest outside of class.

My students really like these. They prefer them to textbooks (no surprise) and videos covering similar material.

The tool to create these 'playbacks' is free and open source (currently a VS Code plugin). I have also created the site to share these with others. I am looking for feedback.

I am the creator of a new medium to guide others through code examples. I call them playbacks.

This is an intro book on Python. I have also written books on [C++](https://ourcodestories.com/markm208/Playlist/2) and [Clojure](https://ourcodestories.com/markm208/Playlist/4). I am looking for feedback on the medium.

I am also looking for others to write their own books/tutorials and to create professional portfolios to show potential employers how they do their work. Storyteller is a free, open source tool to create playbacks. Our Code Stories is a site to host them. Authors can post their playbacks for free, make them private, or charge a fee for others to access them.

If you are interested in creating your own playbacks and need a little help getting started reach out to me and I’ll help.

I already posted to the original but thought I would chime in. I like the idea of guiding someone through some code with a narrative. Your tool is very helpful for this.

I have a similar tool but it allows the comments to be added to the code as it evolves:

https://github.com/markm208/storyteller#storyteller

The main difference being that the context of the comment is always in line with code at the point the comment is made. One other difference is that a person can add drawings and audio to their comments.

I am working on a tool that allows developers to walk others through their code. It can certainly be used purely for teaching others but I think there is also value in having developers reflect on what they have done in their workflow:

https://github.com/markm208/storyteller#storyteller

I think the 'live' part of streaming might introduce a high noise factor.

What if the programmer could finish a programming session and then go back and see exactly what they have done and reflect on it? What if they could highlight just the interesting parts and leave the uninteresting parts on the cutting room floor? What if they could supply a reflective narrative describing how and why the code evolved? I think these types of experiences would provide more valuable learning experiences than the typical live code stream.

This is what I am trying to accomplish with my project called Storyteller:

http://www.storytellersoftware.com

There is a longer video demo here:

https://vimeo.com/97711978

(Earlier in the life of the project I also emphasized the tool as a version control tool/replacement but I am backing away from that for the time being)

Was there any reason why this wasn't timed for the summer months?

It seems like a lot of entrepreneurial college students would love to spend their summer working on their ideas. Perhaps it just came together at this time but in hindsight I wonder if summer is a more logical time since students have the free time anyway. The 12K would allow them to easily live/eat too.

I can even imagine involving college professors and students. Then it might disrupt entrepreneurship education in higher ed.

There is something that I have been working on:

https://vimeo.com/97711978#t=0m37s

Ha ha... yes, it sounds painful but imagine you come across a function that you don't fully understand. You can highlight it and watch how that code evolved. The code will be animated very easily (compared to trying to reconstruct the history from some VCS). Most people will never watch (or care about) you writing code but sometimes it may be very useful.

Imagine if the author of the novel had to write those irrelevant scenes anyway in order to get to the good stuff. There might be someone, a literature academic for example, who would want to study that material. It wouldn't be for everyone but there are some who might want access to it. My point is that we are generating this history anyway, so why throw it out? There may be someone who wants to see how the code has evolved. Plus, nobody says you have to watch stuff that is not interesting. There are ways to filter out things you aren't interested in.

I agree with the author that historical information about how a codebase has evolved is important. I would also argue that code comments are not always the best place for this historical information (if you don’t know about the deep past of a bit of code, then why would you want to see a code comment describing some change to it?).

I suggest we take a step back and ask if modern version control is the best way to store historical information. Modern version control systems (git, mercurial, etc.) were built within the last decade or so but they were built with the same constraints as the original version control systems of the 1980’s. They are optimized to be disk efficient (and don’t get me started about their command line interfaces). This is crazy!

We should store much more about the programming process than the data gathered if and when a developer chooses to commit. We should record it all- every keystroke. No human generated source of data is ever going to fill up our hard drives or the cloud. Don’t optimize for the disk!

This data can be used to replay programming sessions so that others can learn exactly how the code evolved. Developers could then comment on the evolution of their code. Think of this as a modern commit message. I am working on a project that attempts to do this:

http://www.storytellersoftware.com

The main problem I see is that code is read left to right, top to bottom (for the most part) but it is rarely, if ever, written that way. The order that decisions are made is almost as important as the decisions themselves. But, we lose almost all of that order or 'context'. Worse, although we can place comments in the code, we cannot attach comments to the evolution of code. Evolutional comments could describe why things are changing in the proper context and make reading code a lot easier.

The OP clearly doesn't believe that he has a responsibility to teach those around him to be better. Imagine that you were the CEO of a company that had one great programmer and four average ones. Don't you think the CEO would want the great one to spread some of his/her knowledge? Now, imagine you were one of the four average developers, wouldn't it seem crazy that you sit three feet away from a great developer but never learn anything from him/her?

Do we want this to be an industry where only the self taught succeed? I don't. I believe there are still some things that I can learn from others. I believe I am obligated to help those around me get better- it should be part of the job description. Pair programming, if it does nothing else, does open up what is normally a solitary activity and gives people a chance to learn from others.

I am working on a tool that helps document how code has evolved that I believe is similar in spirit to this post:

http://www.storytellersoftware.com

I am actively working on it with students of mine.

Here are some thoughts on reading code:

We read code left to right, top to bottom, but how often is it written that way?

We need to be able to see the order that changes are made in order for us to understand them. Deltas in a version control system store the changes but we lose the order. The time in between commits in a version control system is way too long to understand how code has evolved. Because of this (and the loss of order) there is no good way to animate long term differences in a traditional version control system.

There is not a good place to document the reasons why changes are made. We are supposed to write the reasons why in the commit log but we all know we are terrible at that. How easy is it to remember the 50 changes to 20 files that we made since the last commit let alone describe them in a meaningful way? Very hard. This results in one sentence commit messages that are almost useless.

We could alternatively write reasons why changes are made in code comments. But, this doesn't make a lot of sense most of the time. Who wants to read a comment about how some code has changed if we can't see the old version of it anyway?

So, we make changes, and have good reasons why we make those changes, but we don't write the reasons down anywhere. Storyteller permits a new type of documentation to be created. It animates the changes to code and allows the developer to comment on the changes as they are being animated. Developers can tell stories about why groups of changes are made and distribute them to team members. The stories are searchable from the code.

We are also working on making it have traditional version control functionality to completely replace so-called modern version control (even the most modern vcs seem to be built with 1980's constraints- disk optimized, clunky command line interface, poor visualizations of changes, etc.)

If you are interested in seeing code examples from a text editor or IDE we are working on Storyteller:

http://www.storytellersoftware.com

Everything is stored locally and the tool can generate an HTML playback file that can be passed around. One can also make comments during the playback. There tends not to be a great place to document how code evolves, we think a playback is the best place for this.

Its not quite ready for prime time yet but it will be soon. Our long term goals are to make a web app to store playbacks and to make it the next generation of version control.

I am working with some students of mine on something like 89, 'Code Journeys'. We call it Storyteller.

http://www.storytellersoftware.com

It allows one to comment on the evolution of code rather than on individual sections of it. Currently, there is not a good place to write down why things have evolved the way they did. There is a search/filtering interface to find only the interesting bits of history.

Playbacks can be a great way to learn. I believe git does not provide enough data about the programming process. I am creating a version control system where playbacks are first class citizens. With playbacks developers can create stories about how their code evolved.

http://www.storytellersoftware.com

All keystrokes are recorded but that is not the main form of documentation created. A developer creates a playback of only the 'interesting parts' of the code and provides a narrative about why they think it is interesting.

Then, when someone looks at some unfamiliar code they can search to see if there is a 'story' about that bit of code. The code and the narrative playback side by side. The noise can efficiently be bypassed.

That information can and should be recorded somewhere. The most natural place (I think) for it to be recorded is along side the code where the insights are applicable. The tool was built to allow developers to create these 'stories'.

If you're a really good developer it is true you might not get a whole lot of value from watching a playback. If you're a really good developer, though, it is difficult to take the time and effort to teach all of your less experienced team members about what you have learned while writing the code and to become better programmers. These playbacks offer a relatively efficient way of letting good developers teach once and have many developers learn.

If you're not a really good developer the question is how do you become one? It is possible to learn the hard way by doing (like you suggested), but it is painful. A playback is not just watching the code as it was developed but it is listening to the developer explain why they are doing things. My hypothesis is this will make it easier for people to become better.

"Files are not the best representation of code, just a convenient serialization."

I agree. Files (and version control systems) leak a tremendous amount of valuable information. They are a very '20th century' technology.

I'm working on a tool that behaves like a distributed version control system (branching and merging) but stores more fine-grained information about the programming process. This information can be played back and developers can tell a story about why the code is the way it is:

http://www.storytellersoftware.com