Contribute to READMEs

Open source development is booming and many people, developers or otherwise, are eager to jump onboard! Lots of people have approached me asking how they can get involved in open source projects and how I stay afloat in the ever-changing ecosystem of open source. My answer is: “by editing READMEs”.

Large reach. Large importance.

READMEs, especially those that exist in GitHub projects, are one of the first things that users and developers see when coming across a project. Tom Preston-Werner, the Cofounder of GitHub, even suggests README Driven Development. This means that the README is one of the most highly viewed documents in any repository and so its quality can make or break whether the project receives any further attention.

Having a good README shows that care went into the project and that documentation is treated as a first-class citizen in the project. Your contribution will impact all those that read the README. That’s huge!

In addition, GitHub, one of the world’s largest respositories of open source projects, makes this super easy. You’re only a couple clicks away from making your first contribution to your favourite open source project.

Valuable and harmless.

Many people are intimidated by editing real code in projects because they feel that their code contributions might be heavily scrutinized, or introduce bugs into the project which will reflect negatively on them. Many highly technical developers constantly struggle with imposter syndrome, especially outside the comfort of their own projects. I suggest editing the README of a project first because it’s hard to break things in a static document. Whether you’re fixing a grammatical mistake, spelling error, missing documentation or adding links to important related resources, contributions to READMEs vary widely and can be as small as a single character diff.

Technical and non-technical.

Both technical and non-technical people can contribute to a README equally. Although many open source projects focus heavily on code, a README comprises of both technical and non-technical parts and both are equal playing field when it comes to contributions. As mentioned previously, even grammatical issues are fair game when it comes to legitimate edits.

Gauge project health.

One of the most important reasons that I suggest you edit READMEs is that your small edit can quickly establish a relationship with the maintainers of the project and allow you to evaluate how they proceed to handle your contribution and the overall health of the project.

For example, if your contribution to their README is never addressed in any form, the project is likely carelessly maintained and you should be careful when contributing to other aspects of the project to ensure that it will receive any attention at all. In this case, I wouldn’t spend a lot of time on further contributions until I’ve established a closer relationship with the maintainers to ensure that my time isn’t completely wasted on a project that has been silently abandoned. If this happens, at least you didn’t spend countless hours carefully adding a new feature complete with tests and documentation only to be given the cold shoulder.

On the other hand, if your contribution is quickly addressed by the maintainers, you can further gauge how they handled your contribution. Were they friendly? Did they give you advice on how you can further expand on your contribution? Did they accept it and thank you for the contribution? All these things can give you hints as to how the maintainers will treat you in the future if you continue to contribute to the project.

Get comfortable with the project.

There are many ways to learn about a project but one very effective way is to read the current README and learn from what has already been wrote, then investigate the project and cross-reference what the code says versus what the README documents as truth. Here you can find gaps in the documentation that you can fill, or errors if changes were made to code but the README was neglected (a very common issue I see). Another idea is to follow links in the README, both to get familiar with the various documentation external to the repository but also to potentially find dead links. All of these are important to maintaining a healthy and happy open source project and allow you to start contributing today!

Need a repo to get started? Edit my README on GitHub.

Happy contributing!