Criteria and documentation.

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.

No malls or pop stars.

Today (Friday) I’ll be offline most of the day. My wife and I are taking advantage of the kids’ both being at camp so we can head down to Richmond. There’s a museum exhibit she wants to see and I would like to get out and enjoy some 100F summer weather. OK, the second part I kind of made up, but still the museum part will be cool.

Parts of a whole.

I was excited to read all the reports from the recent FUDCon in Santiago, Chile, where many Fedora contributors gathered to share information, teach, and learn about Fedora and the Fedora Project. After being to many FUDCon events, I have to say that it’s one of the most energizing community gatherings I get to attend. There are lots of great FOSS community conferences, but very few have the overwhelming sense of participation from all attendees. The imperative throughout Fedora is to get involved to help improve the project and the stuff we and others create, which naturally leads to a fantastic sense of talent and performance when you’re surrounded by contributors from all over the world.

I was also extremely pleased to see Jared’s incredible performance at the conference — although delayed first by bad weather and then by airline mechanical problems, he finally made it to the FUDCon, stepped off the plane and onto the podium (so to speak), and delivered his first keynote, in Spanish no less! I always regretted not being able to visit the previous FUDCon events in LATAM, so I’m glad to see Jared showing our commitment to the LATAM community, an essential part of our global Fedora family. In LATAM we have a very robust set of local communities, and like every part of Fedora, each brings its own culture and enthusiasm to free software through Fedora.

In Fedora, we’ve taken a number of steps to allow those local communities to flourish, including helping them set up community sites that support their audience in a local language. Although our websites and other services do offer a great degree of internationalization (i18n) to support other languages, not every service is equal in this respect. And in many cases, local audiences want to exchange information that unfortunately doesn’t mesh well with US law. Since Red Hat, which shoulders the vast majority of our project risks in legal terms, has to live by that law, enabling community sites helps contributors provide appropriate information for their regions without accidentally creating more risk. (Mairin Duffy has been writing about upgrades to our website that will help community members find local resources more easily, in fact.)

As more and more local communities develop, though, we should remember that we’re one united Fedora Project, as opposed to many disconnected groups. The essential component of the Fedora Project we can’t do without, regardless of where we are in the world, and just like every other open source project, is communication. If communication doesn’t happen regularly, it’s very easy for any team or local community to feel they’re not being heard. And we want people not only to be heard, but also to hear. We maintain a huge set of communication services — our official lists, blogs on the Planet, and bot-facilitated public IRC meetings held openly and transparently.

Whether it’s planning a FUDCon event, sorting out code issues, or figuring out how to on-ramp new contributors, let’s make sure we’re using those channels, and using them together.

Shall I bring the car around?

Yesterday, Jared and I drove down to Raleigh. Jared starts Red Hat’s new hire orientation today, and this was a good opportunity for me to stop by the office and take care of a couple in-person tasks. Last night we had a wonderful dinner with Max at Taverna Agora — I had some fantastic lamb chops and we had great conversation. We discussed with Jared some of the things he needed to know about internal mechanics like where Fedora’s budget comes from, and where the Fedora team fits into the organizational structure in Red Hat.

Both Max and I are very excited to see Jared set up his own agenda for leading Fedora, which I know he will be thinking about during and after his travel to FUDCon Santiago tomorrow and then FISL 11. Being down in LATAM will give Jared a great opportunity to find out how our Fedora community operates there, meet some of the active contributors involved, and ask what they need to be even more successful in the future.

In just a few minutes, I’m heading out to locate the remaining Fedora tablecloths for our Ambassadors to use. The always dependable Joerg Simon talked to the rest of the Ambassadors steering committee and other Ambassadors, and sent me a list of destinations. Two of the cloths are already in circulation in the USA. Two more will be heading to the LATAM region with Jared — they’ll be going to Ambassadors around the region for use at upcoming shows. The others I’m mailing to APAC and EMEA.

I set up a meeting for Jared to meet Red Hat’s CEO Jim Whitehurst, and we’ll have lunch with some of the Community Architecture team and Red Hat VP of Open Source Affairs Michael Tiemann. I’m also trying to pick up Jared’s laptop early today so I can get Fedora 13 onto it — we won’t have a lot of time tomorrow, since we also have meetings scheduled with the Brand team, the Legal team, and the Corporate Communications team. Somewhere in there we’re also going to get a new photo (head shot) of Jared. I plan to stand around holding his bag for him while this happens, now that I’m being demoted to his caddy.

So it’s going to be a busy couple of days. After I drop Jared at the airport tomorrow evening, I’ll be driving home and back online more consistently on Wednesday. For the next few weeks I’ll be operating as sort of a backup for Jared, since we’re not sure what his connectivity will be like in Santiago and Porto Alegre. Paradoxically, his robust travel schedule in the first few weeks is likely to help us with the transition of workload, and I’m working on a schedule of release-related tasks for his use as well.

OK, now I’m off to find some swag!