Contributing to Open Source: A Beginner’s Guide (Part 1 of 2)

The following is a guest post by Kevin Curtin and originally appeared on his blog. Kevin is currently a student a The Flatiron School. You can learn more about him here, or follow him on twitter here.

The single biggest surprise since I started my journey to become a developer has been discovering the ethos of sharing that exists among programmers. Especially in the Ruby community, I’ve found that there is a willingness to answer questions and help people for no other reason than to share knowledge and help other programmers create great things. While this is often expressed in a Stack Overflow answer, help on an IRC channel, or access to experienced people at a local meet-up, it also comes in the form of open-source projects.

As beginners, it’s easy to think that we have nothing to offer the open-source community. After all, we are still in the early stages of learning and can’t even begin to comprehend how the gems and frameworks we depend on work. This attitude is understandable, but misses an important point: Open-source projects have _many_ moving parts and consist of more than just code.

What should I work on?

Documentation

Documentation is the first thing that people read when they are getting ready to use a project. Despite this, documentation is often the last thing that gets attention and there are tons of projects out there with little-to-no documentation (or information that is just plain wrong). It’s difficult for an experienced developer who is actually building a project to provide thorough documentation and they almost always assume certain knowledge that other people don’t have. In their defense, it’s a ton of work to go back and create thorough documentation after spending days/weeks/years of donated time actually building the project. Luckily, this provides a great opportunity for us. As beginners, we are in a perfect position to discover holes in documentation!

The truth is, we rely on documentation more than other people because it’s so difficult for us to figure out how to use something by reading source code. We can identify holes in instructions because we almost always “feel” them when we end up trying to follow steps exactly as written and things breaks. By identifying these holes and correcting them, we can help each-other and improve the quality of open-source projects! Enough talk, let me give you an example of how simple this can be. Here is my very first open-source commit, notice that it’s only 3 lines!!!

To say I was excited when this was accepted would be a HUGE understatement (I went to the Github page for the gem and hit refresh 20 times, not quite believing that my example would be one of the first things people see when they visit the project page). The snippet above is just a few lines of markdown that show an example of a type of insert that the sqlite3 ruby gem supports. It was referenced in a Stack Overflow thread that I only discovered after hours of trying to find some type of manual work around. I figured other people would benefit from the additional example and submitted a pull request adding it to the documentation. If you have pain when trying to use something, it’s a good idea to try and get the solution (whether you found it on your own or referenced somewhere else on the internet) included in the documentation.

In Closing

I think that it’s super important for us to contribute because we rely so heavily on many of these projects. If we all work at contributing examples or adding clarifying information to the documentation of projects we use, it will benefit the community as a whole and make it easier for us when we try using a new gem or project.

If you already have an idea for documentation you want to fix, stay tuned for Part 2 of this post, “How Do I Submit a Pull Request?”

-kevin

PS Here is a link to the thread where I submitted the request 🙂

Disclaimer: The information in this blog is current as of October 16, 2012. Current policies, offerings, procedures, and programs may differ.