I've tried this idea out before (on three occasions, with different approaches, but the same name :P).
I think this approach has a lot of promise. Compared to normal blog posts, being able to see the diff and the entire snapshot of the code at this step is luxurious.
The biggest problem I always ran into was that it's brittle. Made a mistake creating the gitorial on step 3 of 10? You have to rebase, which throws off all your commit hashes down the road. You can get around this with automatically creating tags for the steps, but the fact of the matter is, it's brittle.
I also don't like that it's a CLI only tool. When I'm reading tutorials online, I don't want to have to leave my browser—on mobile, I can't leave my browser!
For the purposes of prototyping, these are the two attempts I've had at creating a similar experience in the past:
I've been trying to something sort of along this line with my "Practical Redux" tutorial series ( http://blog.isquaredsoftware.com/series/practical-redux ), as well as other technical blog posts. I kind of fell into the pattern of writing the initial code for the next post, then going through it again as I write the blog post and cleaning up the commits to be more coherent. The post walks through the "final" commits step-by-step, links to each commit on Github, has code snippets for files in those commits that show either a diff or the entire file contents, and also links to those specific file versions as well. I've been manually copying and pasting commit hashes and links into the posts, which does take work, but it hasn't been worth trying to automate yet.
That is a valid point -- I had to get quite used to git rebase while making the initial gitorials =) If all you need to modify is the commit messages, this tool apparently is a nice option:
In the future, I'd like to extend the shell tool to have a nice "edit mode" that runs git rebase underneath. I haven't thought through how to deal with merge conflicts, though.
Being able to run the tutorials online would be ideal, but that will require a full-fledged OS to run the project. That could be done server-side with a sandboxed OS ($$$) or, intriguingly, perhaps it could be done entirely client-side using an in-browser Linux emulator:
It would be cool to make a tool for 'playing back' git repos like this. I could see it having media player style controls so you can jump anywhere in progress, step to the next or previous commit, etc. At each commit, you could have a rendering of the diff, along with interspersed annotations. Maybe there could be a format for annotations, so multiple people could submit annotations for the same repos (or subsets of repos), and you'd end up with different tutorials.
So, in order to make one of these tutorials, you feed the software the url to the repo, start/end commit hashes, and some JSON or whatever that contains your annotations—and it gives you back an interactive presentation of annotated diffs.
With a business like this it's more important to make it easy on the content providers than optimizing the user experience for consumers.
At some mass the algebra changes and it's all about making consumption seamless.
This is the right direction. I encourage the author of this to really think about the experience of making the tutorial for the next few months as the business grows.
I think this approach has a lot of promise. Compared to normal blog posts, being able to see the diff and the entire snapshot of the code at this step is luxurious.
The biggest problem I always ran into was that it's brittle. Made a mistake creating the gitorial on step 3 of 10? You have to rebase, which throws off all your commit hashes down the road. You can get around this with automatically creating tags for the steps, but the fact of the matter is, it's brittle.
I also don't like that it's a CLI only tool. When I'm reading tutorials online, I don't want to have to leave my browser—on mobile, I can't leave my browser!
For the purposes of prototyping, these are the two attempts I've had at creating a similar experience in the past:
- https://github.com/jez/vim-as-an-ide (how to configure Vim & use plugins)
- https://scottylabs.org/wdw/frontend/lab/ (intro to JavaScript by making a simple board game)
Neither my two solutions nor the OP's solutions are perfect, but the idea in general holds a lot of promise.