How to write an Awesome README

If you are in a hurry and just want the template skip to the bottom (not cool).

The rest of the cool people get ready to take your first step to being a README MASTER! (absolutely not clickbait).

You have just created this awesome project and you shared it on GitHub. You think now you’ll just sit back and wait for the world to tell you how cool your project is. After all, you have worked tirelessly for the past month on this very challenging project, right?

Well, let’s just take a step back and look from the perspective of a developer or a user checking your project. Although you know how cool your project is, and how it is going to solve that one pressing problem that hasn’t been fixed(until you came along), the person would be looking at your project and wondering what in the world you have built.

If nobody can’t figure out how to use your software, there’s something very bad going on.

If people don’t know what your software does, then they won’t use it or contribute to it and they will most likely find something more clear and concise in the sea of open-source software.

That’s where the README comes in!

A good README is like the face of your project. It is the first thing a person looks at in your project and it gives them a very brief introduction to your software.

A good-looking and helpful README file can make your project stand out and grab attention from the developer community.

It will help them understand your project, how they can get it working and why they should contribute.

“Wow, man! Nice rant there! If you know so much about stuff why don’t you tell us how to write then…”

Hey, I can’t tell you that there is a concrete set of rules and you should follow those rules without swaying for a good README.

It doesn’t work like that.

I will share how I write a README for my Open-Source projects and things that you should consider while you write one for your projects and you will(hopefully) be able to get some insights.

Also, remember that you won’t be the README master in a day. Like all things, it takes practice.

I have been contributing to open-source for a while now and a thing I noticed is that all great projects have an Awesome README.

You are on the project page and within minutes you are up and running with your version of the project.

There are a lot of contributors, a lot of pull requests, updated versions being released frequently and they all have the common factor of an awesome README.

A new developer will be able to find all the details to get started like install instructions and contributing guides.

A new user would be able to find how the project is being used with informative screenshots and demos.

“I don’t have time for this, show me the README already!”

Alright, alright, alright (sorry I went a little McConaughey ).

Here is the README file for my project NSFW Filter . I think this is the best README that I have written.

I will go through the different parts of the README that I think are essential to every README.

Here is the link for the README file used in this example. You can also find a template README file that you can directly copy and paste in your projects.

Well, that winds things up.

I bid you farewell my grasshopper with these parting words(of wisdom) from the README Sensei(new twitter handle alert!).