If you are reading this article, it probably means that you are already pushing repositories to GitHub and maybe even contributing to open source.
And if you're using GitHub, it means that you will need to write good documentation for your projects to help others understand them.
If you are just getting started using version control, don't feel left out – this guide is also for you. It'll help you learn how to get started writing helpful documentation.
When I started to pushing my projects on Github, honestly I had no idea what a README file was (even though I could see it in other people's projects).
As time went by I started following other developers. They all had cool projects and had contributed to open source, and they all had one thing in common: their projects had detailed README files.
So my interest in what a README was grew, and I decided to try and add one in my projects, too.
In this article, we'll learn more about what a README file is and how to write one.
First, Why Do I need a Good README File?
A README file is a guide that gives users a detailed description of a project that you have pushed to your repository.
Perhaps you are wondering why you should spend time writing a good README. Well are some reasons to help convince you that it's a good idea:
- A good README helps your projects stand out from a bunch of other projects. It should be as good as the project itself.
- It is the first file a person will see when they encounter your project, so it should be fairly brief but detailed.
- It will help you focus on what your project needs to deliver and how.
Just as Friedrich Nietzsche said:
A good writer possesses not only his own spirit but also the spirit of his friends.
When writing a README, always keep in mind that you will need your friends, or in this case other developers, to understand your code.
For instance have a look at this project. As you can see it does not have a detailed README, a description, or any guidance.
With a project like this on GitHub no one will be able to understand what it does no matter how much time you took creating it, right?
Now have a look at this project. Here, you are able to understand what the project does, what it entails, and how to get started if you need to use or want to contribute to the project.
You see, that's the power of writing a good README.
So let's get started
There's not one right way to structure a good README. But there is one very wrong way, and that is to not include a README at all.
These steps are among the best practices I've found. As you progress in your career, you will develop your own ideas about what makes a good README and how to improve on it.
A README needs to answer the following what, why, and how:
- What was your motivation?
- Why did you build this project?
- What problem does it solve?
- What did you learn?
- What makes your project stand out? If your project has a lot of features, consider adding a "Features" section and listing them here.
How to Writing a Good README file
Here are the steps you should take to write your README.
Include Your Project's Title
This is the name of the project. It describes the whole project in one sentence, and helps people understand what the main goal and aim of the project is.
Write a Description
Your description is an extremely important aspect of your project. A well-crafted description allows you to show off your work to other developers as well as potential employers.
This is an important component of your project that many new developers often overlook.
The quality of a README desccription often differentiates a good project from a bad project. A good one takes advantage of the opportunity to explain and showcase:
- What your application does,
- Why you used the technologies you used,
- Some of the challenges you faced and features you hope to implement in the future.
A good README helps you stand out among the large crowd of developers who put their work on GitHub.
Add a Table of Contents (Optional)
If your README is very long, you might want to add a table of contents to make it easy for users to find what they need. It helps them navigate to different parts of the file.
How to Install Your Project
If your project is software or an app that needs installation, you should include the steps required to install your project. Provide a step-by-step description of how to get the development environment running.
How to Use Your Project
Provide instructions and examples so users/contributors can use the project. This will make it easy for them in case they encounter a problem – they will always have a place of reference.
You can also include screenshots to show examples of the running project.
If you worked on the project as a team or an organization, list your collaborators/team members. You should also include links to their GitHub profiles.
Also, if you followed tutorials to build that particular project, include links to those here as well. This is just a way to show your appreciation and also to help others get a first hand copy of the project.
List the License
This is the last section of most README. It lets other developers know what they can and cannot do with your project. If you need help choosing a license, use https://choosealicense.com/
🏆 The sections listed above are the minimum for a good README. But you might also want to consider adding the following sections.
Badges aren't necessary. But using badges it just a simple way of letting other developers know that you know what you're doing.
Don't know where to get them from? Check out the badges hosted by shields.io. You may not understand what they all represent now, but you will in time.
How to Contribute to the Project
If you created an application or package and would like other developers to contribute to it (an open source project), you will want to add guidelines to let them know on how they can contribute to your project.
Go the extra mile and write tests for your application. Then provide code examples and how to run them.
Those are the main steps you need to write your first README!
Now that we have gone through the steps, I believe you are ready to add READMEs to your projects to help make them stand out.
If still need a bit more guidance, you might also check out these examples:
Also check out this guide by navendu-pottekkat
Do share your valuable opinion, I appreciate your honest feedback!
Enjoy Coding ❤