John Poelstra wrote in his blog about how objective criteria support sustainability in an open source project. It was insightful and I wanted to follow up about how that extends to process documentation as a whole.
Lots of people talk about documentation as “that thing you do when you’re finished building something.” But in an open source project, where you’re trying to attract people to help you build or make, that’s an unworkable approach. It’s something you do to make sure that people with skill and energy, who want to help you, have what they need to get started. You want to ensure they can learn the required bits without you having to hold every individual hand, because if you do that, you can’t work on the project yourself. By writing everything down somewhere, you give people the opportunity to self-serve when it comes to learning the basics.
Sometimes acronyms are obfuscatory, but sometimes they help. The “standard operating procedure,” or SOP, is an acronym we do use quite a bit on some of our teams, because it’s a great shorthand for saying, “the stuff you need to know to accomplish a task with minimal or zero help.” An up-to-date SOP document makes it possible for anyone to carry out mechanical steps, observe and report the results, and take follow-up actions if needed. Our Infrastructure team has one of the most comprehensive collections of SOPs in the Fedora Project. But other groups are starting to catch up, like Release Engineering and QA. (Some teams don’t categorize their SOPs like this, which is fine — the point is not what they’re called, but that people can find the procedures and follow them.)
It’s tempting to think that some processes are so important or fiddly that we can’t turn them into SOPs. But I believe those are precisely the ones we should be investing in documenting. It boils down to these simple ideas, which I believe are intrinsic to the open source way:
- The more we believe our work can’t be reproduced by someone else, the harder it is to get anyone to help with it.
- By extension, the more we believe our work can’t be reproduced by someone else, the less likely we will solve the “eaten by raptors” problem*.
People like Mel Chua have written (and practiced!) exhaustively on combating this problem, and often the solution is as simple as “teach someone now, and make it the student’s job to document while learning.” Paradoxically, teaching someone with a lower level of general skill can be more helpful than teaching someone who needs less tutelage. Doing so can expose the specific prerequisites, which otherwise might be just hazy notions (“the practitioner needs to have a high skill level in ___”).
Ideally, anyone in Fedora ought to be able to be absent at any point in our release cycle without unduly affecting any of our release processes. The more we make it possible for any contributor to follow a process like judging against criteria, producing media and art, spinning release candidates, and so forth, the closer we get to that goal. The result is a more sustainable Fedora Project.
*The “eaten by raptors” problem, simply put, is that having institutional knowledge locked up with a small number of people represents substantial risk in a project. This is especially true when the number is one, or if the project is an open source effort. To mitigate the risk that your project will suffer if any member is eaten by velociraptors, eliminate knowledge silos wherever possible.