Today, we’re releasing a handbook to help open source projects prepare themselves for events.

Here’s why: over the last year of Open Source Comes to Campus, we’ve given more than two hundred people the tools and the opportunity to contribute to open source projects.  But not every student is able to submit a patch or pull request.  The biggest obstacle by far? Confusing documentation and poorly defined tasks in the projects they’re trying to contribute to.

A group of students at our Purdue event faced this obstacle.  They spent all afternoon trying to address a bug in Privly.  Their description of the problems they encountered: “lots of downloads, need an approved account to have access… had to create own database on localhost… tears clouding vision”.  Although they were good-humored about it (see the picture above), they never were able to work on the task they’d picked.

At OpenHatch events, we’ve adapted to this common roadblock by requiring that the projects we present to students do a few things, including testing their installation instructions, identifying good tasks to work on, and being available during some of our events.  We call these OH-affiliated projects.  Putting these benchmarks in place has helped us increase the number of contributions at events, and decrease the frustration.  We’d recommend that any event organizer ask the same of participating projects – especially if their event is geared towards newcomers.

To help open source projects prepare themselves for events, we’ve written a handbook aimed at making projects easier to understand, install, and contribute to:

The In-Person Event Handbook

It’s a short, practical list of steps to you can take to improve the odds that newcomers will be able to contribute to your project at a hackathon, workshop or sprint.  For each recommendation, we’ve included an example of implementation from our own project: OpenHatch.

The guide is, itself, an open source project (licensed CC BY).  We welcome your feedback and contributions: you can share advice and submit changes via email, the issue tracker, or by submitting a pull request on Github.  You can fork the guide as well.

We hope you find this helpful, and that it increases the number of successful contributions – and the number of happy contributors – to your project.

You can learn more about what OpenHatch has been working on (and support it with a donation) on our 2014 fundraising page.