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

A Lean, (Ever)Green Machine: Website Tips for Small Shops

I've been making little websites to serve up information on various topics for close to two decades. I'm basically a one-woman shop, so my websites have to be lean, evergreen, low cost and low maintenance to make any sense at all. I currently live in a small town and I sometimes attend public meetings where people are enamored of shiny tech but don't know how to use it. They get all envious of projects and talk in glowing terms about "Wouldn't it be GREAT if we did something like that?!" and I bite my tongue and don't say "You have no idea what on earth you are talking about. You have neither the resources nor the expertise to do a project like that." Those experiences inspired me to write this post. I would love to help people in the small town where I live to establish an effective web presence, but I really am going to need to do a lot of educating if that is ever going to happen. Most locals have no idea how to make a website that'

My First Pull Request Was Approved! Huzzah!

A few hours ago, I submitted my first ever pull request . I mean to something other than the Hello World project Github walks you through to show you the basics. It has now been approved by the maintainer and merged. And, wow, I need to get this off my chest: You programmers are completely unnecessarily scaring off non-programmers from your Open Source projects. This is how this went down: I saw a piece on Hacker News that interested me and I opened it up to find that it was a Github repository. I began reading the documentation and noticed a typo. One of the titles said "Funtion" instead of "Function" in it. So I was like "I would like to tell them." Now the last time I wanted to tell someone in Open Source they had a typo, I left a comment on Hacker News to do it. They did fix it and apparently took some of my other advice as well. But this time the article didn't have a lot of comments. It only has two, in fact. So I felt like le