In my open source courses, I spend a lot of time working with new developers who are trying to make sense of issues on GitHub and figure out how to begin. When it comes to how people write their issues, I see all kinds of styles. Some people write for themselves, using issues like a TODO list: "I need to fix X and Y." Other people log notes from a call or meeting, relying on the collective memory of those who attended: "We agreed that so-and-so is going to do such-and-such." Still others write issues that come from outside the project, recording a bug or some other problem: "Here is what is happening to me..."
Because I'm getting ready to take another cohort of students into the wilds of GitHub, I've been thinking once more about ways to make this process better. Recently I spent a number of days assembling furniture from IKEA with my wife. Spending that much time with Allen keys got me thinking about what we could learn from IKEA's work to enable contribution from customers.
I am not a furniture maker. Not even close. While I own some power tools, most were gifts from my father, who actually knows how to wield them. I'm fearless when it comes to altering bits in a computer; but anything that puts holes in wood, metal, or concrete terrifies me. And yet, like so many other people around the world, I've "built" all kinds of furniture in our house--at least I've assembled it.
In case you haven't bought furniture from IKEA, they are famous for designing not only the furniture itself, but also the materials, packaging, and saving cost by offloading most of the assmbly to the customer. Each piece comes with instructions, showing the parts manifest, tools you'll need (often simple ones are included), and pictorial, step-wise instructions for assembling the piece.
IKEA's model is amazing: amazing that people will do it, amazing that it's doable at all by the general public! You're asking people to do a task that they a) probably have never done before; b) probably won't do again. Sometimes you'll buy 4 of some piece, a chair, and through repeated trial and error, get to the point where you can assemble it intuitively. But this isn't the normal use case. For the most part, we buy something we don't have, assemble it, and then we have it. This means that the process has to work during the initial attempt, without training. IKEA is keen that it work because they don't want you to return it, or worse, never come back again.
Last week I assembled all kinds of things for a few rooms in our basement: chairs, a couch, tables, etc. I spent hours looking at, and working my way through IKEA instructions. Take another look at the Billy instructions I included above. Here's some of what I notice:
- It starts with the end-goal: here is how things should look when you're done
- It tells you what tools you'll need in order to make this happen and, importantly, imposes strict limits on the sorts of tools that might be required. An expert could probably make use of more advanced tools; but this isn't for experts.
- It gives you a few GOTCHAs to avoid up front. "Be careful to do it this way, not that way." This repeats throughout the rest of the steps. Like this, not that.
- It itemizes and names (via part number) all the various pieces you'll need. There should be 16 of these, 18 of these, etc.
- It takes you step-by-step through maniplating the parts on the floor into the product you saw in the store, all without words.
- Now look at how short this thing is. The information density is high even though the complexity is low.
It got me thinking about lessons we could learn when filing issues in open source projects. I realize that there isn't a perfect analogy between assmbling furniture and fixing a bug. IKEA mass produces the same bookshelf, chairs, and tables, and these instructions work on all of them. Meanwhile, a bug (hopefully) vanishes as soon as it's fixed. We can't put the same effort into our instructions for a one-off experience as we can for a mass produced one. However, in both cases, I would stress that the experience is similar for the person working through the "assembly," it's often their first time following these steps.
When filing a GitHub issue, what could we learn from IKEA instructions?
- Show the end goal of the work. "This issue is about moving this button to the right. Currently it looks like this and we want it to look like this." A lot of people do this, especially with visual, UI related bugs. However, we could do a version of it on lots of non-visual bugs too. Here is what you're trying to acheive with this work. When we file bugs, we assume this is always clear. But imagine it needs to be clear based solely on these "instructions."
- List the tools you'll need to accomplish this, and include any that are not common. We do this sometimes. "Go read the CONTRIBUTING.md page." That might be enough. But we could put more effort into calling out specific things you'll need that might not be obvious, URLs to things, command invocation examples, etc. I think a lot of people bristle at the idea of using issues to teach people "common knowledge." I agree that there's a limit to what is reasonable in an issue (recall how short IKEA's was). But we often err on the side of not-enough, and assume that our knowledge is the same as our reader's. It almost certainly won't be if this is for a new contributor.
- Call out the obsticles in the way of accomplishing this work. Probably there are some things you should know about how the tests run when we change this part of the code. Or maybe you need to be aware that we need to run some script after we update things in this directory. Any mistakes that people have made in the past, and which haven't been dealt with through automation, are probably in scope here. Even better, put them in a more sticky location like the official docs, and link to them from here.
- Include a manifest of the small parts involved. For example, see the lines of code here, here, and here. You'll have to update this file, this file, and that file. This is the domain of the change you're going to need to make. Be clear about what's involved. I've done this a lot, and it often doesn't take much time when you know the code well. However, for the new contributor, this is a lifesaver.
- Include a set of steps that one could follow on the way to making this fix. This is espeically important in the case that changes need to happen in a sequence.
These steps aren't always possible or practical. But it takes less work than you might think, and the quality of the contributions you get as a result is worth the upfront investment. In reality, you'll likely end up having to it in reviews after the fact, when people get it wrong. Try doing it at the beginning.
Here's a fantastic example of how to do it well. I've tweeted about this in the past, but Devon Abbott's issue in the Lona repo is fantastic: https://github.com/airbnb/Lona/issues/338. Here we see many of the things outlined above. As a result of this initial work, one of my students was able to jump in.
I want to be careful to not assume that everyone has time to do all this when filing bugs. Not all projects are meant for external contributors (GitHub actually needs some kind of signal so that people know when to engage and when to avoid certain repos), and not all developers on GitHub are looking to mentor or work with new contributors. Regardless, I think we could all improve our issues if we thought back to these IKEA instructions from time to time. A lot of code fixes and regular maintenance tasks should really feel more like assembling furniture vs. hand carving a table leg. There's so much to do to keep all this code working, we are going to have to find ways to engage and involve new generations of developers who need a hand getting started.