README Template - The only one you need for perfect readme

In the Open Source world, the most powerful and useful document is a README file. It is a multipurpose thing, How..? Let's see that, It servers as the documentation for your project, it servers as the landing page too on your repository. So, it alone has the power of making and ruining your game. Then it's worth it, it should look professional and presentable as well.

Most of us spend lots of time on it because we are confused like what all things I should include in my readme file and make it professional + attention grabber. What is the use of having a readme if it doesn't fulfill its purpose?

So, this is the sole purpose of this article and you won't regret reading it and I am sure you will definitely take away something new.

What topics this article will cover..?

1. What is README?
2. What you should include in your README?
3. How to make your README memorable?
4. All-in-one README Template for you

TL;DR - Does it seems too long to read, skip to the end, and get my template

What is README?

README is a simple markdown file present in the root directory of any project whose sole purpose is to convey to the reader what this project is about, how to use the project, and some guides for installation and setup, etc. In simple words, it serves as the documentation, landing page of the project as it is the only most visible thing in a repository, it includes everything an end-user must know about. That is why the filename is written in all caps so it catches the reader's attention first.

What to include in a perfect README?

OK, we know what is readme but what to include in a perfect readme file.

1. Name of your project
   Give your project a name it is a must-do thing. How would a user tell someone what he is using..?

2. Introduce your project
   Introduce your project to the reader. Write four to five lines about your project, these questions will help you What it does? What is the purpose of building it? Who it is for?

3. Features of your project
   Present an ordered list of all the features your awesome project has. You may include all the core functionalities and core features.

4. What you used for building it
   Tell your readers what all things you used to build this awesome project. Use bullet points for it.

5. How to get started?
   This section will guide your project users that how to start using your project this will include sub-sections:

   • What are the prerequisite? - If your project needs something beforehand then include them here so that the user may not end up in an error loop, for eg: your project needs python 3 or Node so list them using bullet points.

   • How to install? - Under this, you should include step by step procedure to install your project right from the beginning.

6. Todo a must-have thing
   List all the things you plan to do or add to the project for eg add <this> feature <that> functionality. Why it is important to have? Suppose the reader wants to contribute to your project, so this will help him/her as they will know exactly like what should they work on? And this way both parties get benefited as your project will get a tick on todo and the contributor successfully done open source contribution.

7. Mention your future plans for the project
   Mentioning your plans gives a positive impression to the reader that you are serious about what you do and will also sound professional.

8. How to use
   Tell the user how he/she can use your project and take benefit from it. You can include screenshots, code examples, or anything relevant.

9. List all the authors
   Tag all the authors with their profile link and also optionally you can mention what they did as the author in the project.

10. How to contribute to the project
    Provide all the steps needed to contribute to your amazing project. You might have seen in various projects they tend to have a separate contributing.md file where they add a guide for the contributors briefly, you can also follow a similar approach in your project and add a link to that file in your README.

11. Credit all the contributors
    Make sure you give credit to your project's contributors as they gave part of their precious time to your project. Also, it's a nice way to make Open Source feel like teamwork or a family. And it will motivate them to do more open source as well.

12. Add LICENSE information
    Add license information if it applies to your project. As others are likely to use your project. You can use chooselicense to find an appropriate license for your project.

13. Link all the resources
    You should link all the resources you used or took advantage of like articles, videos, or documentation, etc. So, that the reader could also go through them.

14. Add acknowledgement
    If you have used someone's work {code, design, etc} or you took inspiration from someone then this is the right place to acknowledge them. Or sometimes you may be using something that is copyrighted and requires an attribution so you can do that here.

How to stylize your README and make it stand out?

There are several ways to make your README visually appealing and attractive, I'll tell you some of the most common ways.

• Add project logo - The very first way your project could stand out is by simply adding a logo to your project and add that in the README at the top just before the project heading.

• Add badges and shields - You can add badges or shields to show various things like it can show the number of issues, the number of pull requests, and what license has been used in this project. They look pretty cool in the README, I'm sure that you have seen them before on. You can use Shields.io to create shields and badges for your own project.

• Add demo GIF/Screenshots again, a must - Make sure you include a demo gif/screenshots of your project (very important) because the reviewer may or may not have time to visit your live project so watching this he/she will get a sneak peek at the project and may visit it later. And also you have to update them when you update your project.

• Add emojis - At last, you could use emojis in your README, nowadays lots of projects are doing this as it adds emotions and colors to it so it tastes more like human and less boring and robotic.

My all-in-one Template for perfect & awesome README

I've created a template for you that has all the recommendations made in this post + some extra stuff too. You can use this template to create your next project repository. If you feel like adding something or have any idea, fork it and create a PR and I'll definitely consider it. You may customize it as per your needs. You can find my template on GitHub here.

EndNote

If you like this post, please show some love and support by liking and sharing it. And consider subscribing to my newsletter to get such useful posts directly on your mail.

---: ALL THE BEST & KEEP HUSTLING :---