📌 The Readme is a guide that contemplates the main purpose of your project, technologies used, some how-to's (such as how to install and how to use it), the license, and how others can contribute.
Readme files have the .md extensions, so it means they need to be using the Markdown standards. It's easy to learn and you can use this editor to write your file more easily.
Your file needs to be easily readable and organized in a way that you, and others, can understand and use as a resource while developing, testing and using your project. Use titles and sub-titles, divide it into sections and make it structural. Write short paragraphs, use bullet lists and highlight important content using bold.
Remember, your project's Readme is the first impression someone will have of your project, and you don't want it to be sloppy and badly written. So let's check the best way to create your Readme file!
What does your README needs?
Name
This is the name of the project. It can be the name you are giving to your product or what type of project it is.
Description
Here you are going to add what your project does and what are you planning to add to it. Write shortly about what technologies you used and how you used them. This part is a summary of all you worked on, be brief once you will get into more details on the rest of your Readme document.
Table of Contents
This is more to make everything more organized. The more you write, the harder is to find information. Create your table of contents and separate your sections in it.
Technologies
It's time to add everything you used in your application: languages, libraries, APIs and more. Did you use it? You name it! This will help you and future contributors to keep track of everything used to build the project. Also, is a great way of sharing great tools with new learners.
Install and Run
Here you will explain, step by step, how to install and run the development environment. Add the code, if necessary, and explain how to do it for the different types of operation systems, if needed.
Usage
Hopefully, you developed the project thinking about your end-users needs. Now it's time for you to explain to them how to use it. I know you think your app is all intuitive, but it is great to make sure the end-user knows how to use the projects and all the features that might help them. You can do a small tutorial, a walkthrough or even, use bullet points with all the application functionalities.
Contributing
If your project is open-source, you can add this section to show how other developers, testers, designers and users can contribute to it.
Add the how-tos:
- How to report a bug?
- How to make a pull request (PR)?
- How to get support?
- How to make a donation? (If you want to let people make donations for it.)
And also add some guides:
- Coding Style Guide
- Styling Guide
- Code of Conduct
This part can be a bit bigger than the others and you might want to separate it into different files.
Acknowledgments
Add what inspired you to create the project (other repos, YouTubers, books, etc), what resources you used (documentation, websites, courses, etc) and who helped you build this project. I also suggest you tell a bit about yourself, once you developed the project and deserve the credit!
License
Developers often forget about it, but adding a license is key to make sure it will show other developers the limits of the use of your software. To do so, you should add a file to your project called LICENSE.md or just LICENSE, where you will add the full copy of the license, with your name and year in it.
For the Readme file, just link the license under the license section.
Extras
These are extra things you can add to your README.md file to make it look more complete. They are just a recommendation and you can do it if you want (most of it is just to make it look more aesthetically pleasing).
Images
This will help your Readme feel less like a bunch of text. These are some ideas:
- Add your project logo right next to your project name.
- Add screenshots of your application in the usage section to demonstrate to the end user how your app works.
- Add a photo of yourself on the credits so people can identify you more easily (or an avatar that represents you - I do most of mine on the Picrew website).
Status Badges
I'm not a big fan of this one but you can add status badges on your Readme using the badges/shields repo. This will illustrate, in a simplified way, your project status.
Emojis
I am a big fan of using emojis in your Readme file. They help it become more visual and easy to read (and it looks cool 😎). Make sure you add emojis that make sense to the subject and do not overload your file like I do sometimes.
Examples
Here is a repo list of great Readme files for you to get inspired:
https://github.com/matiassingers/awesome-readme
And if you are lazy and want something ready to go, I made this Readme file for you to copy and edit to your necessities. If you liked it, don't forget to give it a star!
Top comments (0)