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.

What is 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.

What to Include in a README File

Project Description:

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.

How to Install the Project

If the user has to install the project on a local device, you should include the necessary steps to install your project and the required dependencies (if any).

How to Use the Project

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.

How to Contribute to the Project

Include instructions on how other developers can contribute to your project, if you intend to collaborate with other developers or if the project is open-source.

Credits

You should include a list of people you worked with on the project if you worked on the project as a team. You can add their GitHub profiles.

License

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.

Also...

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.

Enjoy 🖤

Notes on GitHub READMEs