If you want them to RTFM, make a better FM.
— Kathy Sierra

One of the scariest moments of any engineer’s life is the moment before sharing their code with the world. Whether it’s a pull request for your employer or a commit to an open-source project, you’re about to open yourself up to feedback, debate, and sometimes even criticism. This can be especially scary for more junior engineers, fervently hoping they got everything right and won’t look stupid when they click “Submit.”

In a professional environment, you can (hopefully!) assume a limited and supportive audience for your contribution. In an open-source project, however, this might be your first interaction with the community. On top of hoping your code is acceptable and useful, you often don’t know the standards and norms, who the players are, or the collection of odd processes and esoteric rituals—like those around approval workflows and house styles—that develop in many communities.

There is a way, however, to reduce the fear, make a good first impression, and learn more about a new open-source community: writing documentation. Documentation is a vital part of any project. Yet few open-source projects can claim they are well documented, and many others struggle to keep their documentation up to date. (Some notable exceptions include Django, jQuery, and SQLite—these are worth looking at as model examples.) Documentation is also the entry point into a project for most people, and a lack of good documentation inherently limits its reach. By contributing to documentation, you can help attract new users (and potentially new contributors) to a project.

It’s important to mention that this article assumes you want to get involved in open source. This is a complex decision for many folks, especially those who don’t have the economic or logistical flexibility to contribute. The spurious association between contribution to open-source software and employability is also a concern. I recommend this excellent article by Ashe Dryden as a starting point if you’re interested in these issues.

With that said, let’s look at some ways you can start contributing to open source through documentation, starting with how to find projects to work on.

Finding a project: Contribute to what you know

My first exposure to many open-source projects is via a need. When looking for new projects to work on or determining who might need some help, I usually start with projects that I am using or intend to use. I might have a feature to build or a problem to solve, and I ask myself: “Is there prior art? Can I take a shortcut by ‘buying off the shelf’ instead of building myself?” I google or search GitHub and find a repository that contains a library or tool that might help. I then examine that repository to see if the project meets my needs, and I usually do a quick health check on it, too, to see how well it is maintained. If the project seems to meet my needs, then it’s time to try it out. By using it myself, I can start to identify whether I can improve the documentation or make life easier for the next person trying it out. I find it ideal to make contributions when the project and my experiences in implementing it are fresh in my mind.

I also recommend using referrals. If you have friends who work on open source, they’ll often know which projects are friendly to new contributors and might make a good place to start.

You can find a number of good examples of open-source documentation and other excellent resources at the Write the Docs community.

Once you’ve found a project, you’ll want to keep in mind some basic contribution etiquette as you get started.

Etiquette

Approaching a new project can be less stressful if you take a couple of preparatory steps.

First, do some research. Many projects have an issues backlog that details what the project needs—often including gaps in documentation. This is a great place to get ideas for what to work on. It can also give you a sense of the people involved in the project and how other contributors have interacted with it.

Second, review any contribution guidelines. A lot of projects outline these in a README file or a CONTRIBUTING file. These files usually contain instructions on how to contribute to the project—guidelines on where and what to branch, testing, and continuous integration, or community standards like code linting or formatting. The instructions should help you ensure that your contributions are in line with community standards.

Third, ask where the community needs help. You can follow up on an existing issue, for example, by asking if anyone is working on it and volunteering to help or seeking clarification on the best place to start. Or you can contact the maintainer(s) directly and enquire about specific problems or areas they might need help with. Be aware that many maintainers have day jobs or limited time and may not respond immediately. They may also have been offered help in the past that hasn’t eventuated, so sometimes folks can be wary. But most maintainers are super excited to get new people involved in a project.

Sometimes you won’t hear back from a maintainer if you just reach out or update an issue. I tend not to let this stop me from contributing, though that’s a matter of personal preference. I use the information available to me to contribute something, and I find that a pull request often triggers more activity than an update on an issue or an email. In these cases, I recommend providing a lot of context on and explanation of your contribution so the maintainers understand your intent.

Of course, there are open-source projects out there that are not welcoming or friendly. If you get a response or observe behavior in a project’s issues or pull requests that makes you uncomfortable, you’re under no obligation to contribute. Move on and find another project.

Now let’s look at some areas where you might be able to contribute.