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

Me. Woodward Park, Fresno, CA. January 2016.

One of my favorites pics of me.

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

Know Your Audience

Many years ago, I read an anecdote about an American man working in Asia. He was frustrated with his communication difficulties with the locals which ran deeper than simply a language barrier. One day, he felt like he was finally making progress and a colleague of his commented that they were "Thinking along parallel lines." He enthusiastically agreed and hoped this meant their communication difficulties would soon be a thing of the past. He hoped to soon see a genuine meeting of the minds, but much to his frustration, this did not come to pass. It was soon apparent that nothing had really changed. When he asked his colleague "What about what you said about us thinking along parallel lines?" the reply he got was "Parallel lines never meet." The same words can mean very different things to different people. Context helps inform us what is intended but to some degree how your words get interpreted depends on what is in the mind of the person reading th