Getting newbies involved in open source

Newbies: Play your cards right, and this could be you

I’d never expected much response from my last blog post, much less the overwhelming one it received. From following up on the comments alone, I’ve learned more about open source in the last couple of weeks than in the 2 years since I started coding. If you left a comment here or on HN, please trust that it was read and left an impression on me, and I thank you.

Here’s the gist of what I’ve been digging into since then, after dozens of hours of research, writing, and notes inspired by responses to that article.

It’s broken up into 2 parts:

1.) Getting newcomers involved

2.) How newbies can get started

While the emphasis changes, I believe there’s something of value for both maintainers and contributors in both sections.

Part 1: Let’s get newcomers involved in open source


“It’s the small things that count”

Some of the responses to my last post literally said “Get over yourself.” While that’s good advice, the fact that so many others came out as “OSS wallflowers” means that there’s room for improvement in our communities.

The loss of newcomers in OSS really is “death by a thousand cuts”. I can’t really describe to you how many times I’ve nearly given up, persevered, and then finally just quit on a project due to the cumulative friction of trying to pitch in. Besides my prior points, here are a few other places I think people get stuck:

Ugly, painful-to-use mailing lists – So many projects have a barebones mailing list that requires constant monitoring and/or huge amounts of work to pick through to find something relevant. Ugh. Google Groups is a godsend. If you don’t trust Google, you should realize it’s the minimum standard for mailing lists: Mailing list technology from 1996 doesn’t cut it; you’ll need to have forum-like organization for the archives.

IRC – You’ll be surprised how many newcomers don’t realize IRC still exists. Now that I know IRC, I absolutely love it… but don’t assume people know what it is or how to access it.

Jargon – What the hell is “diff and patch”? Is that like “clone and commit” or “fork and submit pull request”? Don’t assume people know your lingo, you might want to put up a glossary. In fact, “help us build a glossary” might be a great way to get someone involved.

Rejection – When turning down a patch, remember to include the long view. It’s easy to say “that’s not how we decided to solve that problem”, but take an extra minute to suggest something that they may be able to do with what they learned during the process.

This is a bigger problem than I realized

The quote from the headline for the previous section is from a report by Karen Rustad that’s so good and well-researched, it makes my prior article completely irrelevant.

The same kinds of obstacles that keep newbies out of OSS also affect women and minorities. This is a huge problem, and one we need to deal with soon.

I know it’s long, but I beg of you, read her paper if you care at all about why there are so few newcomers, women, or minorities involved in open source software:

Does a solution even exist yet?

After writing my last article, I felt compelled to prove that I’m interested in solving the problem of the “open source obstacle course” (as Greg Brown so deftly put it). I wanted to build a simple site to connect newbies with maintainers & supporters of open-source projects that could break down a lot of these walls.

I was surprised to find that such a site already exists:

This sounded familiar:

“Free, open source software loses tons of prospective contributors because it is difficult to learn how and where you can fit in.

OpenHatch is an open source community aiming to help newcomers find their way into free software projects. We work toward this goal through this website and in-person outreach events.”

This was exactly what I was looking for. I’ve had several chances to speak with Asheesh Laroia, the maintainer of the OpenHatch project, and his passion is infectious. While I’ve been loudly complaining, he’s been quietly building, and I love him for it.

Right now, the focus is on larger-scale projects, and my beloved Ruby is quite poorly represented there. But that could change if just a few Ruby maintainers started adding their projects there (i.e. RubyDoc) and using it to recruit contributors.

OpenHatch isn’t perfect. I’d like to see more of a focus on helping me find a project whose purpose, needs, and support structure are a good match for my skills and interests. I’d also like to see less of a focus on specific bugs within projects (not to mention the use of the word “bug” to describe any kind of potential contribution).

But most of the ingredients are there to create something really great: a marketplace for project owners and contributors to court one another and start building amazing stuff together.

For my part, I’m going to be putting my effort into OpenHatch, because I believe in their vision and their community.

Have the conversation.

In digging into this, I was stunned to realize that this conversation is novel in the Ruby community, but has been going on for some time in the Python community.

I think much of this is due to to the fact that Jesse Noller, who seems to carry a lot of weight in the Python community, cares about checking in and having the community self-examine to find the points of friction for new people and trying to smooth them out.

That’s an example I think every OSS community ought to learn from.

Part 2: Help! I’m a newbie, where do I start?


Why contribute?

Many commenters frowned on “contribution for contribution’s sake”. That’s missing the point: there’s no such thing as “contribution’s sake”, there’s always a bigger “why”. Some will say you should never help unless you’re solving a problem you specifically have, but I disagree strongly with that notion. If that were the case, you’d never loan a neighbor a cup of sugar unless they were baking you a cake.

Yes, it’s important to pick a project you care to see implemented or improved, but if your motivations are largely to participate in the OSS ecosystem, I think that’s a perfectly reasonable place to start.

Big project or little project?

There are pros and cons to both. Big projects are intimidating, with lots of nooks and crannies, with their own lingo, and they often make “celebrities” of core contributors. To a newbie, this looks like a party that you won’t get invited to for a long, long time.

But if you can find a project that is geared toward supporting contributors, your best bet may actually be in trying to help document, test, or patch a big project. Most large projects (Ruby, Python, Mozilla, Debian, and many others) have groups dedicated to helping new contributors make an impact.

Smaller projects with a single maintainer might seem easier to break into, but these maintainers rarely have the bandwidth or knowledge to support contributors very well. Either way, look for a support structure that can help you dig out when you inevitably get stuck.This includes looking for some semblance of existing documentation, which sort of means a catch-22 for projects looking for documentation help.

“Start with documentation” may be an uphill battle.

It’s amazing how much you can learn about a technology by documenting it. It’s also amazing how much context you need to have in order to document a piece of software.

I’m extremely pleased that I’ve recently started contributing documentation to an open-source project, but I drastically underestimated the difficulty of “documentation”. This is not creative writing, it’s technical documentation that requires an understanding of the technology you’re writing about.

If you’re a newbie, and a project has essentially zero documentation, it’s not likely you’ll be of much help, unless there’s someone there who will walk you through the ins and outs of the project, at length, again and again, until you get it well enough to explain to others.

Don’t expect too much handholding

In the future, I believe we’ll have systems to help onboard newer developers, but for now, you are going to have to get out a machete and clear your own path much of the time.

A good rule of thumb is that if you haven’t spent at least a few minutes searching and trying to solve an issue yourself, don’t bug a maintainer about it. If you can’t get help from a maintainer even after trying to do a lot of that legwork yourself, you may want to start looking for another project to invest your efforts in.

A few projects you can help with right now

Ruby Mendicant University – Free, community-oriented Ruby education

There are many projects in need for RbMU, and if you’ve read my earlier posts (or have attended RailsConf) you know it’s a worthy cause.

ThinkUp – Social network aggregation

They tout “100% nice people” on their front page. It’s safe to say they value contributions.

RDoc – Help document Ruby

The incomparable Steve Klabnik has created a video and instructions on how you (who, me?) can help document the Ruby programming language.

BDSM – Bash shell scripting framework

Wayne E. Seguin is a machine sent from the future to be nice to developers and make their lives easier. You should check this project out for that reason alone, but he also gave me my first OSS commit, so YAY.

Sproutcore – Super-awesome “desktop app on the web” framework

Yehuda Katz posted the understatement of the decade: “Having contributed to a number of open source projects in the past…” They put together one of the best contribution pages I’ve seen.

Sadly, this guide would be VERY hard to find if Yehuda hadn’t linked to it directly:

Resources you didn’t even know you had (at least, if you’re like me)

Don’t know how to get started? Here are some things you can do:

Bugmash – The recent Rails Bugmash in Boulder, CO was wildly successful. Several people got their first-ever commit to the Rails codebase.

User Groups – If you have one in your area, go. If not, start one.

Hack Nights – Whether or not you have a project to bring, don’t be shy, show up and ask if you can pair with someone on an open source project.

Remote Pairing – Ask programmers via Twitter if they’ll pair with you on a project–many will say yes.

Talk to a maintainer – Use a mailing list or IRC to just chat with a maintainer of a project… you may find you have an ability to contribute beyond bugfixes.

Teach others – Creating tutorials or screencasts about a project you use is a great way to discover its ins and outs, as well as a great way to help, without writing a line of code.

Speak out! – It was amazing to see the number of people who feel or have felt like I did. Unexpectedly, writing about my fears and frustrations drew an outpouring of ideas (yes, and criticism) about specific ways I can start contributing, as well as offers for guidance.

Don’t be shy, your community is waiting for you

If you’re wanting to help with open source software but don’t know where to start, the most important thing to realize is that you’re not alone, and that others want to help you make an impact. While it’s nice to know where you’re going, the next best thing is to stop and ask for directions from the locals.

The process of doing so for me has been to realize that the best communities in Open Source foster a culture that is going to be supportive of you asking for help, which tells me that the community is probably deserving of your help. Then, you have an opportunity to help remove some of the roadblocks that scared you at first, and upward it spirals in a virtuous cycle.

Lastly,  OSS culture is great, but there’s not a lot of time taken to come back around and thank people for their work. I want to publicly thank Mike Moore and Jake Mallory, who tirelessly organize the Utah Ruby User Group meetings, as well as Greg, Jordan, and Jia (and my fellow students) from Ruby Mendicant University.

Each of those groups has dramatically impacted my life, and if you’re not participating in them (or something very similar), you’re missing some incredible opportunities.

OK, so maybe OSS is not a shark tank after all. Please do jump in, the water really is fine.

P.S. If you’re a maintainer and care as much as I do about this topic, please visit all the links in this article. They’re written by people much smarter than me, and I could only scratch the surface of the insight they contain.

Please watch this video.

Greg Brown, creator of several open-source projects and the free online Ruby Mendicant University that I participate in, put together an incredibly thoughtful video addressing my most recent post, point by point.

Thank you Greg, it’s incredibly enlightening. I still plan to collect the best of the responses to that post, but by and large, this pretty much covers it.