A crash course on writing a better README

In the wake of the we’ve seen a huge growth in open source contributions. The open-source community has opened over 400 000 pull requests during October alone. That’s insane!

I started looking into projects with large amounts of contributions. It got me thinking. A common pattern started appearing. They all have amazing readme.md files. I doubt it would have been easy to contribute otherwise. There may be a connection. I’d sure say there is!

Let’s mention a few famous projects like , , , or You can see their readme.md’s are a perfect blend of documentation, project overview, FAQ, and contribution steps. They mention the ecosystem, the community, and have visuals explaining the open source project itself.

Because the open-source community runs the project, it needs a central file to make communication easy. It’s a file where maintainers explain all project details, as a guide. But what exactly is a readme.md file?

What’s a readme?

The pillar of any open source project is the readme.md. It contains all necessary information for understanding the direction the project is heading. It explains the software and its purpose. Any prerequisites are also there to make sure new contributors can get up to speed quickly.

The most important part is that it contains steps to get the software running on your local machine for development purposes. But, it should also contain steps to deploy the software to production as well.

Why do you need a readme?

When you want people to notice you and your work, don’t you use a resume, a GitHub profile, or even a website? Well, of course, you do. So do I. The same logic applies to an open-source project. The readme.md is your software’s resume. Add anything you think will make it easier to understand for future contributors.

It’s quite sensible you should first create a readme.md before going public with a project. It’ll make your life as a maintainer or collaborator infinitely easier. Answering questions and helping contributors will become a walk in the park.

That’s why you should make a habit of making it the first file you create in a project. Make sure to place it in the root directory of your project, so it’ll be visible on GitHub.

How to write a readme?

Luckily, you don’t need to reinvent the wheel. There are a few awesome templates you can use. What you need to keep in mind is to have a natural flow in your readme.md. You want it to be easy to understand and simple to start collaborating for everyone who reads it.

Take a look at this amazing template by . It’ll get you up and running in no time.

But, there are a few things missing. First of all, ways of engaging the community more. Feel free to add visuals, badges, images, videos, and even GIFs to your readme.md files! Don’t forget, your goal is to get people to love your project. You can’t forget to give contributors a sense of appreciation for helping out.

Here’s where comes in. It’ll walk you through the whole process of writing an awesome readme.md.

Remember, the key takeaways are to engage the community and appreciate contributors. First, start by adding badges. I love badges! You use them to show build status, test coverage, PR status, vulnerabilities, and what license you’re using. Be bold with these, because they’ll make your project look serious. Social proof is everything in the open-source community. And the best part, you can . Or, copy the ones below. 😉

Another awesome tool that bridges the gap between awesome visuals and appreciating your contributors is .

Mentioning people who built the software is a major step toward getting the community engaged. Let’s be honest, wouldn’t you want to see yourself as a contributor to an awesome open-source project!? I sure would.

Did I miss anything?

What if your project starts growing at an increasing rate? Then you should start thinking about creating a contributing.md. It’s where you put all details about contributing and pull requests. It acts as the official guide for all open-source lovers on how to start contributing to your project. Here’s how it looks for freeCodeCamp.

It doesn’t stop there. First, add a license.md for specifying the level of openness. Then, a code_of_conduct.md to explain general rules and conditions developers should act by. In the end, we should all be awesome to each other. The code of conduct is there to make sure we are.

Wrapping up

Every awesome open-source project has an amazing readme.md, and it makes perfect sense. We, humans, have limited attention spans. We need a readme.md that pops to get potential contributors to start creating pull requests. By looking at repositories like or , you can see a common pattern. Clear explanation of features, content, documentation, contributing guidelines, and engaging visuals.

In the end, you don’t need to reinvent the wheel. Use templates. Follow the guidelines above. Engage your community and be awesome towards your fellow developers! That’s what it’s all about. Helping each other create amazing software to benefit humanity. If you want to check out one of my previous personal growth related articles, feel free to head over to , or check it out below.

Hope you guys and girls enjoyed reading this as much as I enjoyed writing it. Do you think this tutorial will be of help to someone? Do not hesitate to share. If you liked it, smash the clap below so other people will see this here on Medium.