This article is also available in Korean, thanks to Dohyung Ahn!
Thom Parkin made a great point in the comments of an earlier article of mine:
Great advice. But you missed one very important [final] point. Since this is Open Source, once you have figured out the details of that feature/function where the documentation is a bit light, YOU SHOULD UPDATE THE DOCS AND SUBMIT A PULL REQUEST. In that way the entire community benefits, and you can even gain some “coder cred” for your participation!
I’m happy Thom mentioned this, because it’s so important. Fixing documentation is the easiest way to start contributing back to the projects you use and love.
My first contributions to projects like Rails, Rubinius, and Elixir have all been doc fixes. I’ve made small tweaks to make things clearer, explained some things that you could only discover by reading the code, even just fixed broken formatting. These have all been quick, easy ways to help out some big open source projects. Even when they’re my only contributions to a project, they’ve still helped future users, and Future Me. And that’s what open source is all about.
Why documentation fixes are such a great way to get started
Doc fixes are the least intimidating way to contribute to a big project like Rails:
-
You don’t have to set up the project in order to fix the bug. Since you’re just updating the documentation, you don’t have to get the tests or the app running. Sometimes, you won’t even have to clone the project to your machine – you can make your change right on GitHub!
-
If the maintainer asks you to make changes to your pull request, they’re usually a matter of wording or taste. Those kind of changes can be easier to stomach than criticism of your code. And it’s easier for you to make those changes, because you don’t have to update tests or code, just words.
-
Documentation is hard for a project maintainer, so updates are appreciated. Often, authors are too close to the code to understand where the confusing parts are. They need other, newer developers to tell them where the docs need help. It takes practice to see your project as a beginner would, and not everyone has built that skill.
-
Finally, you’re starting to build a relationship with the maintainer, with a low-impact change. You’re not changing the direction of the project, like you would if you were contributing an entire feature. So your change is easier for a maintainer to review, and they’ll usually respond to you more quickly. Your merge request won’t get stuck in the “Is this a good idea?” phase.
As you keep building that relationship, you’ll start to be seen as a reliable contributor. Your pull requests will get reviewed faster, and it’ll be easier for both of you to talk through more complicated feature requests and bug fixes.
They’re easier to start, they’re easier to do, and they tend to get merged more quickly. So why wouldn’t your first contribution be a doc fix?
How to start contributing back updated documentation
There’s an important way contributing doc updates is like fixing bugs: They both rely on being sensitive to things that feel wrong. You have to pay attention.
When you run into behavior you didn’t expect, it might be time to update the docs. If you have to dive into the code to solve a problem, you might also want to tell other people about it. You should even be sensitive to broken formatting and typos in the documentation you read. If you’re not going to fix it, who will?
Once you have a good idea of where to make the change and how you want to word it, make your change and send a pull request through GitHub.
If you’re still trying to decide on the best way to update the docs, open an issue on GitHub. It can be something like this:
“Hey, this was confusing to me. I was thinking of updating it to look something like this: … What do you think? Anything else I should mention?” Together, you can come up with wording that satisfies everyone.
Finally, don’t be discouraged if you don’t get a response. Big projects have a lot going on, so it’s easy for your contribution to fall through the cracks. In a week or so, if you still don’t hear from anyone, ask the maintainer again.
Documentation is often the first thing you encounter when you work with a library, so it’s important that it’s detailed and clear.
So when you’re confused about the code you use, or have to dive into the source, make it easier for the next person. Write a quick update, and contribute it back. It’s the easiest way I know of to become an open source contributor.
This article was originally sent to the people on my list. To read more like it, sign up here!