The first time I saw the word 'README', I was trying to complete a task. The instruction was to create a README.md file; add some information about the project, and push it to my GitHub. I didn't quite understand its purpose until I had to work on a collaborative project that required deployment.
Coding best practice requires that every repository has a README file.
A README File is a text file that gives users the basic required information about your project at a glance. It describes your project, states why your project is valuable, what users can do with your project, and how they can use it, among other things. It is usually the first thing people engage with when they check out any project you have on your repository. It needs to be concise.
A properly drafted description includes the following:
a. Your project name;
b. What your project does;
c. Who the target user is;
d. How it works; and
e. The technologies you used and why you used them
The project description allows other developers and collaborators to have a high-level understanding of what your project entails.
Be sure to guide users on how to use the project. Provide step-by-step instructions. These instructions will be a reference point when users encounter any difficulty.
You can make the instructions more interactive by using visual aids like screenshots or clips to show examples of the running project and results when users adhere to them.
Also, if your project requires authentication, this is the right section to include the credentials.
There are various types of licenses. The one you can choose depends on the kind of project you are creating. The license helps collaborators know what to do and what not to do.
If your README is very long, you might want to add a table of contents to make it easy for users to navigate to different sections easily. It will make it easier for readers to move around the project with ease.
Keep it up-to-date - It is good practice to ensure that your file is up-to-date. Make sure to update it when necessary.
Be concise and include only the required details. Your documentation should contain all other information.
There are tools you can use to automatically generate a README for your project.