LearnContributing to Open Source Documentation

Open Source software, languages and frameworks have enriched our lives greatly. In fact we wouldn’t have the web in its current form today without Open Source software. Most of the technologies used for serving, programming and viewing websites are Open Source. Individual contributions may be small but the sum of everyones contributions are what we see when we see things like Apache, Firefox, Ruby, Rails, Node.js and jQuery being released into the world.

Open Source is fueled by the work of talented contributors and developers. Without their hard work, often in their free time, we wouldn’t benefit from their work.

Often we can feel a little overwhelmed with the idea of going into a project and giving back. Maybe you don’t feel your coding skills are up to the task. But you can contribute in more than one way to projects. You can help with documentation!

Understanding code is an important part of learning to code and writing documentation, however trivial, shows an understanding of not just the code but of people who are trying to access it.

There are a number of ways you can contribute to the documentation. Some have a wiki interface like Mozilla’s MDN or others allow you to contribute through GitHub.

Contributing on GitHub

I’ve contributed to a number of projects on Github over the years, often very small edits, from updating a typo in Sizzle, jQuery’s selector engine, to clarifying the instructions on a README.md.

Let’s take an example of how we’d start to contributing to a project. We’ll use gulp as an example.

1. Look for and read the CONTRIBUTING.md file

Normally open source projects have a CONTRIBUTING.md file in the root of the file system. In gulp it looks like this:

Open it up and you’ll see how to contribute.

• ideas: participate in an Issues thread or start your own to have your voice heard.
• resources: submit a PR to add to docs README.md with links to related content
• outline sections: help us ensure that this repository is comprehensive. if there is a topic that is overlooked, please add it, even if it is just a stub in the form of a header and single sentence. Initially, most things fall into this category.
• write: contribute your expertise in an area by helping us expand the included content
• copy editing: fix typos, clarify language, and generally improve the quality of the content
• formatting: help keep content easy to read with consistent formatting
• code: Fix issues or contribute new features to this or any related projects

Out of the seven ways to contribute, code is the last one. So there’s plenty of ways to help out.

However it does ask you to be familiar with pull requests and markdown formatting.

2. Fork the Repository

Once you’ve figured out what you want to contribute hit the fork button at the top right.

You may be asked where you’d like to fork it if you’re part of an organization.

I’m going to select my own github account.

If you don’t see this you’ll have already forked it onto your own account.

Notice how in the top left there’s your username followed by the repo name and below, where the originating repo is.

This means you have it forked correctly.

3. Find and Edit

Next find and edit what you want to improve, clarify or document. You don’t need to download the repo. You can actually edit right there and then in your browser.

I’ve found in the FAQs.md a question:

Is it “gulp” or “Gulp”?

gulp is always lowercase.

However I’ve seen an exception, in the logo. So I’m going to click on the edit button (pencil).

And I’ll modify the line so it now says:

gulp is always lowercase. The only exception is in the gulp logo where gulp is capitalized.

4. Commit

Scroll down on to the bottom of the page and you can see where you can put your commit message. I’m going to write “Referenced to the capitalized gulp in the logo.”

Then press the button “Commit changes”. You can see what the commit looks like here.

5. Create a Pull Request

Then click the pull requests tab on the top right of the file viewer.

Click on the “New pull request” button. GitHub looks at your commits and compares them to the original repo and asks you to “Create a pull request”. Click that button.

You’ll now see the commit message as the subject of your pull request. You can also flesh it out or add additional information in the text area below.

I’m going to write “Added exception to the ‘always gulp’ FAQ.” Then we can finish it off with “Create pull request”. You can see the pull request here.

6. Wait

Now it’s a waiting game. If the owners of gulp accept it they’ll merge in my changes into the repo. If not they may ask me to change the wording slightly after having a discussion in the comments on the pull request. Or they may just reject it. Which is fine, it’s all practice.

Conclusion

It’s fairly straight forward to contribute to projects without the need to even code.

Why don’t you find a library or framework you use and help them out in the form of documentation.

• code
• git
• source control