Cracks in the pavement

Note: this is my first post in the #trust30 “Ralph Waldo Emerson Self-Reliance” project. In the project, you commit to writing a bit every day in response to a given prompt. Today’s prompt is “the story you’d tell with 15 minutes to live”.

So many of my memories of being twelve years old are of what the pavement looked like. I remember relishing the different textures, the deeply-pocked slabs of gray, the brick-red squares. I found it comforting to watch myself propel the sidewalk behind me, its cracks passing in a rhythm that helped pass the time.

Besides, it was only practical. I would never trip on anything if I was always watching my next step.

This also provided a shield from onlookers, avoiding the discomfort of coming into eye contact. I hated eye contact, it always seemed to carry some kind of judgement with it.

But my shield was constantly under attack. My dad sharply criticized my posture, saying that my constantly staring at the ground was one of the reasons that I was picked on and bullied; that I brought it on myself. He was right, naturally.

I tried to correct my posture physically, at his advice, as if this would somehow change my entire perspective on life. Just as naturally, it didn’t.

As I got older and started deciding that I was a fundamentally good human being with intrinsic value, I began noticing that I hardly ever looked down. I began tripping on things periodically. I would smile to myself each time, a little bit proud that I’d graduated past the safety of watching my steps.

Now, my memories are of the faces of people I care deeply about, people I care less about, and people I barely know, if at all. I don’t have any idea if they had to fight for their ability to look around and see others, rather than watching the ground whoosh by.

I hope that when my eyes meet those of my young son, he sees approval and his immense value to me and to the world. I hope this becomes a model he can use for the rest of his life.

I think he’s going to be okay; he surely trips and falls enough.

Some of the best programming (or life, in fact) advice I’ve received

via Chat in the Hat/Flickr

“Your problem is not at all what you can and can’t do, but rather your expectation that things should come easy to you.”

Gregory Brown earned his spot in the Ruby Heroes roster more than a year ago, but he’s earned a central spot in my personal constellation of heroes (and friends, if I can be so bold as to claim him).

It’s been about a month since he wrote this to me, after I came into the IRC chat room, feeling like a complete fraud and failure as a programmer. Tonight, I’m rolling that sentence around in my head, and it cuts so deeply to the heart of one of my most cherished beliefs: that I am a smart, talented person who catches on to things quickly.

“You think things should be easy for a ‘real programmer’, and get frustrated when they’re hard for you.”

This belief in my inborn intelligence/talent backfires hard (and there’s a lot of science to back this up) when it comes into conflict with personal experience. When I face a problem I can’t solve alone, I’m stuck. Either I’m an idiot or the problem is so hard as to be unsolvable.

“So you work extra hard, thinking that will help you catch up.”

Historically, I’ve let my ego tell me the problem is unsolvable and I’d give up. Over the last year or two, I’ve discovered that I can throw extra effort at a problem, work day and night, and get some of the same results that more experienced people get in half the time.

But this is a hack! It’s unsustainable, and only temporarily props up my belief that I can accomplish these “out of my league” problems alone. Sooner or later, I’ve vacuumed the joy out of the problem-solving process and learn to fear and avoid it altogether. I believe this may be one of the primary sources of that complex state we call “burnout”.

“Just get the help you need from those who will spend time teaching you.”

This is the ultimate ego smasher: asking for directions. It’s so simple, so why don’t we do it more often? If you’re a programmer, you almost certainly know programmers smarter than you who know the lay of the land and would be happy to help.

Men famously hate asking for help, while most women I know find the “I must persevere alone” mentality ridiculous. This point of gender differentiation is one of the reasons I think it’s an absolute crime that we don’t have more women in programming.

“Most ‘easy’ programming things are only easy because you’ve done them 100 times and learned them years ago, not because they were easy to learn.”

Ultimately, patience with yourself is at least as much a virtue as other forms of patience. It may perhaps be the sigle most important kind. Dave Hoover, in his excellent Apprenticeship Patterns book, really tries to get you to reframe, moving the camera back so that you can take a view of your skills in terms of decades, not weeks or even years.

Lastly, it’s important to find that person or group you can turn to in the moments you feel stuck and inept. I am fortunate to have an awesome support structure through friends I’ve met in the Utah Ruby Users Group and Ruby Mendicant University.

Thanks Greg, for the advice and for giving me a place to go when I feel stuck. If you can be as patient with yourself as Greg has been with me, you’re going to turn out just fine.

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.

My notes from Greg’s video response

Not a post per se, but I thought I’d collect my notes from Greg’s video here for my purposes. Excellent advice throughout if you care about OSS at all. (You should still watch the video.)

The desire to get a sticker that says “you’re ready” is social conditioning that is incompatible with the diversity of work needed in open source. Being ready is just a commitment to help and a project compatible with any of your skills.

“The skills you’d need to help this project” and “ticket difficulty” would be good clarifications for maintainers. Also, “Newbie friendly” projects should clearly say that they offer more support.

It’d be nice to have a place where projects were centralized and organized by topic advertised for contribution

Not knowing where to start is OK, you just have to be able to deal with running down a couple of blind alleys first.

Failing at pull requests is winning at learning the project.

Bugmashes are a great way to dip your toe in the water and it means you’ve got a built-in invite.

Contribution guidelines may not be how you’d work in isolation, but are typically critical for the long-term viability of a project. Your patch is a one-time commitment for you, but the maintainer has to live with it forever. Keep that in mind.

Guidelines should be stated up front. For non-conforming contributions, maintainers could apply fixes for that first time, and provide feedback for future contributions.

Maintainers are as busy as busier than you are. Fixing & integrating your patches can take longer than doing the work themselves.

Not every maintainer is interested in contribution, and those who aren’t should probably put up “noobs keep off the grass” signs.

“Open source is for people who are better at this than me” is flat-out false.

Finding a bug (either organically or via a tracker) and writing a failing test case is a great way in. From there, trying to actually fix the problem is a great way to learn a codebase.

It’s a bit unfair to expect maintainers to be community-builders as well as hackers.

You shouldn’t expect immediate praise for a patch you submit, as it takes time to review and safely accept a patch. When not accepting a patch, a maintainer doesn’t always take the time to explain why they didn’t accept it.

Maintainers need to remove as many hoops as possible or risk losing many, many good contributors.

If you need a hand to hold, that’s OK, go find someone outside the project (like a coworker, user group, pair programmer, or hackfest)

If hacking takes you too long, you may have picked too large a problem. Try thinking smaller and solving an easier problem.

“The idea that you’re supposed to learn this stuff on your own is patently false.”

The idea of trying to privately study until you’ve arrived as an open-source coder is a recipe for failure.

If you just want to contribute, shop around a bit for a good fit for you, i.e. high level of developer support.

Expecting a vibrant, barn-raising community or a shark tank is drawing too sweeping a conclusion. It’s an ecosystem made up of smaller cultures. This means you need to find someone to help you find the subculture that fits you, and then work toward making the whole ecosystem better.

You probably have more resources at your disposal than you know… In my case, I could have used community resources already at my disposal rather than writing a frustrated 2 AM blog post.

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.

Why I still don’t contribute to open source

Via zen on Flickr

I am such a hypocrite. A few months ago, I posted about overcoming my fear of contributing to open source software.

Since then, I still haven’t really participated. On Twitter, I commented that OSS looks like a shark tank to newbies, and I need to back that up.

The fact is, I actively contribute in some fashion or other in several open source projects. But I still feel very much like an outsider, as my contributions aren’t typically code-related.

So why am I (and I assume, many others) still an OSS wallflower?

At the profound risk of projecting my feelings onto other people, I would like to share some objections that I feel may cause new(ish) devs to shy away from contributing to open source software.

There’s no certification, ceremony, or merit badge that says, “you’re ready to contribute to OSS”. (Though there is one for afterwards.)

It’s not obvious where to start. From what I hear, a lot of OSS contribution comes because a person needs functionality in a piece of software that isn’t there, or finds a bug. They can submit a failing test case or even a patch. In my daily use, I don’t run into many of these situations. There aren’t many devs sticking their hands out asking specifically for help on a project, and fewer still who would be willing to take a newer developer under his or her wing.

Guidelines often make a maintainer’s life easier, and mine harder. Yes, maintaining an open-source project is an arduous, thankless task. But I’ve looked at contribution rules/guidelines that turn a simple idea for a fix into a bureaucratic brick wall worthy of Microsoft. A notable contradiction to this would be Wayne Seguin’s welcoming contribution page, complete with tutorial video.

Open source is for people who are better at this than me. I realize this is probably a copout for not shipping, but I am just not comfortable that I’m at a place where I could release software that’s good enough for actual developers to use.

Trying to contribute and failing makes me feel stupid. I’ve submitted several pull requests now and had 0 accepted with no comments as to why. It’s like the universe is confirming that yes, I am an idiot, and my “help” is not helpful. What a profoundly embarrassing waste of time!

There’s no time. I have a kid, a new gig, and a mounting set of responsibilities. It takes me 3-10 times the amount of time to write code as a more experienced developer. Now, my non-code-related contributions are now eating up my former “coding time”. Yes, it’s the universal excuse, and one that I think melts away when the other excuses are removed, but it bears mentioning.

It’s pretty lonely. I think most people figure this stuff out on their own, and so maybe expecting a hand to hold is too much. But is this really some spirit walk, where no one is allowed to accompany you, lest you learn nothing?

So yes, OSS can feel daunting, even like a shark tank. I don’t have all the answers to these issues, but I’d like to see more maintainers seeking contributions with some specificity, and then actively responding to pull requests. A call for additional test cases. Bug fixes. And yes, documentation.

For all the openness of Github, there’s no Quora/StackExchange-type system to let you know which projects are in need that you might be a match for. Seems like that’d be a good feature.