Skip to main content

Sticky This: See a typo? Submit a pull request.

For the first time ever, I submitted a pull request yesterday to an open source project notifying them of a typo. It was accepted within hours.

Submitting the pull request was easy and took almost no time. The process of submitting it gave me valuable prompts, such as "This field is typically no more than 50 characters."

I've been on Hacker News for over eleven years. I began wondering how on earth I can contribute to open source as a non-coder a few years back.

I've talked to other non-coders who were just as mystified as I was -- or more mystified -- as to how on earth you get into open source as a non coder. So, no, it isn't just me.

I spent probably a few hours yesterday trying to sort out how on earth to notify them of their typo. It took me far, far longer to figure out what I needed to do than it took to do it. This is a huge barrier to entry and will stop most people before they begin.

Most people simply can't give you three hours of their time to tell you "You have a typo." Even those who can sink that much time into it, why the hell should they?

It's enormously frustrating that it took vastly more time to figure out what I needed to do than the work itself took. Expecting people to read three hours of instructions before they do five minutes of work for you is beyond unreasonable.

So, no, I don't want to hear "We have documentation telling you how to get involved." What I'm telling you is "That's the problem."

You have too much documentation and nothing that cuts through the crap for someone who has never in their life submitted a pull request because they don't code. Instead, you need something that just cuts to the chase and lets non-coders know "You do that by submitting a pull request. It probably won't take you over ten minutes, even if you have to set up a github account first."

I've asked around and I have always been assured things like "We are friendly. You can join our email list."

Yeah, no, that's the last thing I want to hear from a bunch of coders for a really long list of reasons. The short version is that I hear two things, both of which drive me away:
  1. It will take six months of shooting the breeze before I ever get to do any real work. UGH. So in my mind it will be this HUGE, HUGE time sink that will go on forever before there will be any payoff in terms of actually being able to improve the documentation.
  2. Everyone will expect me to meet their emotional needs and "be their friend" while no one gives a damn about my welfare, as usual, and, no, I am not interested in playing this game at all. Period.
The info I have needed this ENTIRE time was "Oh, just submit a pull request if you see a typo. If you already have a github account, it takes maybe five minutes and there will be pop up messages to help walk you through the process. Then you're a contributor and you are building your github repo. Ta da!"

Here are some of the reasons I think that's a best practice and will likely greatly increase participation by non-coders:
  • Submitting the pull request is the most important piece that is alien to me and which I need to practice. Typos are a really tiny thing with which to practice this more critical skill that is new to me.
  • It looks to me (based on this one experience) like submitting a small update to the documentation probably has a lower barrier to approval and happens more quickly than submitting something to the code base. So it's an experience of quick success.
  • Typos happen. Correcting them doesn't imply I think I'm smarter than you and I don't even need to really understand your documentation to catch a typo, so it doesn't make me feel like "These people are going to HATE me for catching their mistake."
  • It gave me insight into "coder culture" in a way talking to coders never has. Just do the thing without having to talk to people is one of the things that draws coders to code and no one ever told me how to do the thing without having to talk to anyone first. I did the thing and it was fun and I will probably do it again.
So even though it has taken me literally years to get here, having done it once, I am highly likely to submit future pull requests for typos. And that is highly likely to slipperly slope me into knowing more about github and doing other things gradually, over time, at a comfortable pace.

I might even, by golly, finally learn to code. (It's only been on my To Do list since the day I originally joined HN in July 2009.)

This is my third attempt to try to say this effectively. Hopefully, "Three times a charm." (1. 2.)

Popular posts from this blog

Pivoting a Website

The website Aberdeen Art and Music began as an effort to consolidate three older websites into a single website for purposes of trying to create a local walking tour as a tourist asset for this small town. It later took on a new purpose and I was tasked with updating the site to preserve and enhance the existing purpose while making room for new functions. The older websites were static sites that each corresponded to a printed brochure. The brochures and corresponding original websites were logically categorized by type of art: Murals, Critters and Urban Art (mostly sculpture). But much of this art can be found in close proximity in the downtown area, so I wanted to consolidate that information and enhance it to serve as an economic development tool for this small town. The intent was to support a walking tour via smartphone and begin phasing out the printed brochures while still supporting the existing brochures that were still out there and had the old URLs on them. In s

My Work

In the movie The Pickup Artist , Molly Ringwald's character utters my all-time favorite movie line: I'm too truthful to be good. I have apparently always been socially insightful. I was probably the bratty child yelling "The emperor has no clothes" and getting away with being rude, crude and socially unacceptable because I was cute as a button. When you are four, people laugh uncomfortably and don't explain to you why they are laughing. Being four, you stupidly think you are a talented comedian and then you spend your twenties and thirties baffled as to why everyone routinely gives you the death glare and wants your head on a pike instead of appreciating your witty insight and sense of humor. Me being me, I didn't stop being honest. I just tried to find ways to express myself that were less likely to have people wanting my head on a pike. This is a large part of why I blog. I still find social stuff very interesting, I see a need in the world for hig

Local News and Information Online

I recentely read an online article with local news. Nowhere in the article does it actually name the state and the name of the publication is generic enough it doesn't give clues as to the location. I poked around the site and found a county name somewhere, maybe in the same article, maybe in a different article. I googled the city name and the spelling is unusual such that it might be a unique city name though there are definitely other cities with names that sound the same. If this article were printed in a physical newspaper bought locally, using just the city name would be fine. You would know from context exactly which city was intended. But when an article is posted online, people can potentially trip across it from anywhere in the world. You are no longer talking to just locals and even if the city name is unique, not everyone will automatically know that. Don't assume your audience will go digging for more info like I did to try to figure out exactly where