Hacker News new | past | comments | ask | show | jobs | submit login
Tell HN: Open-Source Does Not Have to Be Intimidating to Non-Coders
6 points by DoreenMichele on Nov 9, 2020 | hide | past | favorite | 7 comments
I've been on HN a lot of years and I have wondered how you get involved in open source projects as a non-coder. I've also spoken with other non-coders looking to get involved who felt just as stymied as I did.

Yesterday, I submitted a pull request to correct a typo in the documentation of a open source project. I first spent a lot of time digging through stuff to figure out what I should do (pull request? submit an issue? something else?). A pull request seemed to be the right answer, but I was hesitant to do that for various reasons -- partly because in my mind that's for updating code -- and when I have asked around, no one has ever told me "Oh, you can get involved as a non-coder by submitting a pull request to correct a typo."

When non-coders say things like "Who do I talk with?" or talk about cultural barriers, people try to be nice and assure us "We aren't all hateful to non-coders. Come join our email list for this thing!" And it's the wrong answer.

The correct answer is "None of that matters. You can submit a pull request if you find a typo or other small issue and that's the best way for a non-coder to get involved. It's small. There's no one to talk to. There's no email list to join. Just submit the pull request. They will either approve it and merge it with the master or they won't and no one will bite your head off about it. And now you are contributing to open source. Voila!"

If you want non-coders to get involved in updating your documentation and so forth, you need to find some way to let them know that "All you have to do is submit a pull request." The current approach misdirects people like me into trying to "make connections" to people and all this garbage that is completely irrelevant, counterproductive and a waste of time. It actively interferes with answering the question of "Where do I start?"

You start with a pull request for something small, like a typo. Done. Now you are "a contributor."

Not everyone is using GitHub (some that don't still use git, but some don't; also, some projects are mirrored on GitHub but do not use GitHub for their main development system), so pull requests are not always appropriate. (Not everyone uses mailing lists either.)


A lot of the open source projects I've seen are encouraging. They have a "How to contribute" section in their documentation and a "contributing.md" file in there.

Practically search any project "X contribute" or "how to contribute to X" and it'll be the first thing that pops up in the results. Many specify that you can contribute in different ways, and address the issue of documentation.

However, timing may matter. You're a bit "lucky" since November is right after October, and open source maintainers have had a rough month of "Hacktoberfest" in which a lot of scum of the earth surfaced. I mean by that your valuable contribution was appreciated and the maintainer wasn't biased against it after last month.

The point I am trying to make -- and feel like I am utterly failing -- is that when I have talked with people about wanting to contribute to open source as a non-coder, their replies just increase the barriers to my participation. They don't decrease them.

It may seem obvious to a coder that "Well, you just submit a pull request." -- so obvious that it literally goes without saying -- but it was not obvious to me that this was how I should try to tell an open source project "You have a typo."

I spent probably two or more hours yesterday reading articles, writing and rewriting a question that I never posted on HN, etc. It was vastly more time and effort than it took to submit the pull request to correct the typo.

I'm trying to say: Coders need to help non-coders move those things mentally out of their way. They need to find a way to succinctly tell non-coders that they don't have to jump through all those hoops and spend hours and hours reading through documentation and looking up procedures and joining email lists.

If a writer sees a typo and wants to correct it, they can skip all that stuff and just submit a pull request. It isn't hard. It doesn't take long and you don't have to spend hours and hours doing your homework to find out how to do it.

I started to fill out the form and got a pop-up message "This field is usually less than 50 characters...etc" So filling out the form was the best way for me to learn how to fill out the form.

And no one ever told me that. They just tried to assure me "We are friendly. We are welcoming. You can join our email list."

That just adds a long list of tasks and work to my end of the equation that makes it look to me like "It is going to take a zillion hours of homework and prep work and networking before you will ever be allowed to suggest a change to the documentation, like correcting a typo."

Having experienced it that way for years, I think that is a huge and unrecognized barrier to participation for non-coders. Having gotten replies for years that just made it look to me like "Yep, you need the equivalent of a four year degree from a university before you can correct a typo." I'm telling you that's probably a primary reason you see so few non-coders helping with things like documentation.

You need a sound bite that strips all that away and tells people "See a typo? Submit a pull request!" That's the part non-coders don't understand and aren't being told.

In my opinion as a non-coder who has literally spent years on Hacker News and years wondering "How in the heck does a non-coder get involved with open source???"

I understand. How can you amortize your recent experience while it is fresh?

Let me explain: conventions are powerful. A reason many repositories on github have a "README", "CONTRIBUTING", "CODE_OF_CONDUCT", "LICENSE" files is because of conventions (and sometimes legal requirements).

What would have lowered the barrier to entry for you if you had read it on a project's site or repository?

>You need a sound bite that strips all that away and tells people "See a typo? Submit a pull request!" That's the part non-coders don't understand and aren't being told.

Some sites have that. "See a typo or have feedback?" with links to repository/issues. What would an ideal process for a non-coder be to contribute to any project and/or open-source project?

I've tried to do a write up (for the third time, counting this post to HN) and I've also submitted it to HN, though it probably also won't get traction. Here is the direct link:


And maybe what needs to happen is not so much "sticky this" as just learn that what non-coders really need to hear somehow is "You just submit a pull request for that. Takes like five minutes." and not "We are friendly! Come join our email list!"

Because I'm not averse to reading all that stuff. But if you have to do three hours of reading before you can submit "you have a typo," that is going to drive people away. If I can tell you "You have a typo" and get that approved and it's a positive experience, then I have more motive to start learning about conventions and so forth.

No project maintainer has to deal with unsolicited pull requests.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact