Since writing my post about good-first-bug vs. good-first-experience I've been experimenting with different approaches to creating useful walkthroughs. I think I've settled on a method that works well, and wanted to write about it, so as to encourage others to do the same.
First, a refresher on what I mean by Good First Experience (GFE). Unlike a Good First Bug (GFB), which can only be fixed by one person (i.e., it's destroyed in being solved), a GFE is reproducible by anyone and everyone willing to put in the time. As such, a GFE is not tied to the current state of the project (i.e., rapidly changing), but rather uses an old commit to freeze the state of the project so it can be recreated. Following the steps doesn't alter the project; it alters you.
If we think of an OSS project like a team of climbers ascending a mountain, a GFE is a camp part-way up the route that backpackers can visit in order to get a feel for the real thing. A GFE is also like a good detective novel: you know the mystery is going to get solved by the end, but nevertheless, it's thrilling to experience the journey, and see how it happens. Could I solve this before the book does?
With my open source students, I've tried a mix of written and in-class presentation style. My approach is usually to fix a bug in a project I don't know and document what I do. I think it's useful to put yourself on an even footing with a new developer by working in unfamiliar code. Doing so forces me to be more deliberate with how I use tools and debugging/code-reading techniques. It also means I (mostly) can't rely on years of accumulated knowledge about how code is put together, and instead have to face the challenge fresh. Obviously I can't leave my experience out of the mix, because I've been programming for over 30 years. But I can remove familiarity, which is what a lot of us rely on without realizing it. Try fixing a bug in a project and language you've never worked on before, and you'll be surprised at what you learn about yourself. When I need to humble myself, a few hours with a CSS bug is usually all I need :)
My first attempts at this involved writing a blog post. I've done a few of these:
I enjoy this style. It's easy for me to write in my blog. However I've moved away from it for a number of reasons. First, I don't like how it recedes into the past by being tied to the history of my blog. It's important what I wrote, not when I wrote it. Instead of a journal entry, I want this to feel more like documentation. Another thing I don't like about using my blog is that it ends up being disconnected from the project and code in question. There's an unnecessary separation between the experience and the code, one that I think encourages you to read but not do anything.
I've since started using another style: hijacking the project's README.md file and writing everything in a branch on my fork. First, some examples:
I got the idea for this approach when I wrote my guide on Machine Learning and Caffe. To do this, I needed a combination of documentation, source files, and images. Obviously my blog wouldn't suffice, so I did it as its own repo. I'd seen lots of people "blog" using Gist before (e.g., this Makefile tutorial), and I was curious to know what would happen if I repurposed an entire repo as a writing medium.
In the case of my ML guide, it's meant a ton of exposure (4.5K stars and weeks as a top trending repo), and nearly 500 forks. It's also formed its own community, with people filing bugs and still other people helping solve them. It also resulted in a complete Chinese translation, and thereby yet more exposure.
Knowing that I could use GitHub in this way, I was interested to try an even more symbiotic approach for my GFE guides:
- Fork the repo in question
- Create a new branch, and freeze the project state so it is reproducable by others
- Add a
screenshots/directory for all the images I need to include. Now I can justgit addandgit committhese into the repo - Erase the
README.mdfile contents, and start writing my guide in there. - Link to files within the project, pinned to the commit that I'm on in this branch
I've liked a number of things that this approach provides:
- As an outsider, you can contribute something to a project you like that will help others get involved. I don't have to convince the project to do this. I just do it.
- Similarly, I can do something in the project without having to get permission. I'm not asking any of the projects to make this official documentation. Whether they do or don't, it exists on GitHub identically
- People (my students, or others) who want to try what I'm doing can simply clone my fork, and checkout my branch. All the files are there in the exactly the right state. Everything should work as it did for me. There are obviously going to be issues with environments and dependency versions I can't control as easily.
- People can interact with what I've done to suggest corrections, file issues (just enable Issues on your fork), star the repo, etc.
I taught my Brave walkthrough in class yesterday, and I think it was ideally suited to the time I had (2 hours), and the level of the students. Many times in the past I would have fixed a bug live in class, but I didn't produce a guide that could be used after the class ended. By doing both, I've found that students can watch me do it live, and we can discuss lots of things that are happening; and then after class, they can read through it again, and ideally try it themselves, to further develop the skills.
This approach is something new that I'm enjoying, and I wanted to share it as a possible style for others to try. If you have projects you think I should do this on, let me know. I'm definitely going to try to do more of this.