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.)