Using Github repositories for presentation samples

For the past year, I’ve been creating Github repositories to store the code demos for my public presentations. I’ve found it had quite a few advantages. Now, some other speakers are starting to follow the same procedure (or even extending it). Earlier this week fellow MVP Joe Guadagno asked me about how it works, and then used it for his next presentation.

He also started a broader conversation about the technique on twitter. A number of other speakers chimed in with their thoughts. Twitter has great immediacy, but doesn’t let me explain how I do this at length. In this post, I’ll discuss why and how I use git repositories for code presentations.

Why use Source Control for Presentations?

I’d grown very dissatisfied with the common practice of having a zip file for the starter project and a zip file for the finished code. Way too much information was missing.  My best presentations show attendees more than just what to do. I also discuss alternatives that don’t work correctly, and why. These small side steps are missing when the only assets are “before” and “after”. Missing is “why choose this path?”

What was missing was any roadmap to “tried this, found these problems and changed directions.”

I can preserve all that history using a source control system. In fact, I’d been using my own internal source control for presentation demos for years. I could practice by rewinding the history, replaying the checkins and seeing each step along the way through the demos.

Github has now made that possible for anyone attending the presentation. It’s public, and I can represent each step of every demo as a branch in the repository.

The Process

My process starts after I’ve thought through the demonstration that I want to show during the talk. This hasn’t changed at all: what do I want people to learn, and how will I explain those concepts?

Once I have the story, and the arc of the demo, I’m ready to make the repository. I run through my practice sessions (using git at each step) and the I’m ready to record.

I make the “start” project for the demo. Maybe this is direct from File: New Project, or maybe it’s a starter project that already has some features.I’ll create a new git repository, and make regular commits as I get to the initial state. Once I’ve reached the initial state, I make a branch. For these repositories, every branch starts with a 2 digit number, so that my talk attendees can easily follow along. The first branch is likely “01-Start” or something similar.

I continue to build the demo, by following my script. I use commits for small-grained changes that I want people to follow, if they are working on their own. I use branches for larger-grained changes that I discuss during the talk. You can see each section of the talk by checking out each labeled branch in turn. You can follow each commit to see all the smaller changes that make up each new feature.

One very powerful feature that I use for talk demos s to be able to show what happens down the wrong path. For example, I may make an async demo where I’ll explore the problems that happen from using async void methods. Letting the audience see those mistakes is important for their learning. Using Git, I can explore dead ends, and leave those branches as examples of problems. I can back up and checkout an earlier branch, then show the correct path. Attendees can follow the straight-line path, or check out the dead ends for reasons why certain paths are avoided.

Once I’ve finished running through the script of my demos, I check the repo and the commits and branches in order one last time. I make sure each of the branches can be checked out in order and that each branch correctly represents the next checkpoint in the demo.

On Stage

Having a repository does not mean I don’t write code during the presentation. Before the talk, I checkout the starter branch. There are two rules I follow during the talk:

  1. No one wants to watch me type.
  2. It’s important to show the progress from start to finish.

You may notice that these two rules contradict each other.  I do show some of the changes as I move forward through the demo. But, I don’t type everything out. Often, I prefer doing a ‘git checkout’ to move the code to the next step.

If I don’t get any questions, comments, or feedback on the discussion, the demo goes forward from its starting branch to its final branch. I’ll mix typing some of the changes (or using the Visual Studio tools to make large-scale changes, depending on the demo), with using git to move forward by checking out the next branch.

Because I’ve done some typing, git complains when I want to roll forward from branch to branch.

One important tip is to remember to do a ‘git checkout –f’ so that you don’t have to stop, rewind anything you typed, and then move forward.

I can also go off script to answer questions or respond to different feedback. This changes the demo, but I can get it back on track by checking out the next branch.

I don’t have hard and fast rules for when I type vs. when I roll forward in git. My heuristic is that when attendees will learn from seeing the code typed, I type it in. When that transformation is not instructive to the topic, I roll forward. I’m not certain I always get this right, but I like the guidance so far.

At the end of the talk, I tell attendees the URL of the repository, and tell them to explore.

After the talk

Github provides several tools to continue the conversation with attendees after the talk. I’ve used all of these after different talks.

  1. Code Review Comment (or question): Attendees can use github to view any commit, and ask questions about the code. Those questions may be about the topic of the demo, or can be unrelated questions. I like handling those unrelated questions this way, because it doesn’t change the fundamental story of the talk, and attendees do get their questions answered.
  2. Fork and Pull Request: Sometimes I’ll have attendees ask why I wrote code one way vs. another. They can fork the repo, and show me their idea in a pull request. Sometimes I explain my reasons and the attendee learns something new. Sometimes the attendee has a better idea, and I learn something new. Either way, it’s great.
  3. Fork and Branch: Sometimes an attendee wants to take the project in a new direction. They can do that by forking the repository, and extending it on their own. It’s no longer about the original talk, and I’m happy to see that it inspired someone to do something new.

This process is still somewhat new, and I’m sure I’ll continue to refine and change how I do it in the coming years. However, I really like where it is heading.

What do you think?

Created: 12/22/2014 7:55:04 PM

Current Projects

I create content for .NET Core. My work appears in the .NET Core documentation site. I'm primarily responsible for the section that will help you learn C#.

All of these projects are Open Source (using the Creative Commons license for content, and the MIT license for code). If you would like to contribute, visit our GitHub Repository. Or, if you have questions, comments, or ideas for improvement, please create an issue for us.

I'm also the president of Humanitarian Toolbox. We build Open Source software that supports Humanitarian Disaster Relief efforts. We'd appreciate any help you can give to our projects. Look at our GitHub home page to see a list of our current projects. See what interests you, and dive in.

Or, if you have a group of volunteers, talk to us about hosting a codeathon event.