We mostly tend to ignore the README file as a trivial non-essential part of your project. However, a good README file is what an Index is to a Book. README file enables users to navigate and identify essential elements of your project quickly.
Most often, when we create any new project using a bootstrap library such as create-react-app, it comes with a default README file. In the case of create-react-app, it is README.md at the root folder. Unfortunately, it was my habit to ignore the default README file in my projects. At times, I've even deleted it mercilessly, thinking of myself as an Efficient developer who is just removing non-essential parts. But lately, as I have learned about the importance of maintaining a good README file, Believe it or not, README is one of the most crucial parts of your project in the long run.
Who do you write README file for:
For your present and future self:
Even if you write a project just for yourself and expect no one to use it in the future, or you may never want to publish your code publicly, even in that case, a sound README file will keep you accountable for your project goals. It will also act as your permanent reference point for essential particulars of your project. For example, you may open your project after years, and README will quickly jog your memory and prevent hours of struggle in remembering important project specifics.
For other contributors:
Suppose your project has or gets too many contributors. In that case, it will be a time-consuming and redundant effort to teach every single contributor about your project specifics. Furthermore, we all have our style of coding and maintaining file structure in the project; hence, it would not be reasonable for you to expect them to understand your project by going through your project files.
For users:
Your project may have many non-dev users just looking to run it quickly and consume it for their specific needs. For example, suppose your open-source project is a popular library to be used in other projects. In that case, your README file is the single most important critical aspect of your project success to get more downloads.
What should you write in your README file:
Brief overview of your project/tool/library
It should be a short and straightforward explanation of your project that explains its purpose and goals and your motivation behind developing this project.
Index - Table of Contents
It is pretty handy for users to have an Index containing a list of topics in your README file. If your README is in HTML or MARKDOWN format, don't forget to add anchor links to your index for quick navigation of your README file, it is becomes essential if your README is too long.
Tech stack that you have utilised for your project.
This will give a concise idea to technical users of your project if this project is compatible with their specific usage or not. For example, declaring that you have utilised creat-react-app bootstrapping for your project will save developers a lot of time articulating how to run your project. This may also include any specifics for the required development or production environment for your project.
How to run your project
This section should consist of a list of possible steps or commands to run and evaluate your project. This may include specific commands to aid for development and production environment.
Change log:
It is good to maintain and enlist different Version changes in your project over time; this will depict various changes your project has gone through and help long-time consumers of your project in troubleshooting problems and identifying that may relate to a specific version of your project.
References and Credits:
Always give credit where it's due. This section may enlist possible references that you have utilised to build your project and acknowledge credible contributors to your project.
Here is the example README file from one of my new project. Or you may use following template:
I hope this guide about writing a suitable README file helps you.
Top comments (0)