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 🖤
References
- https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
- https://www.makeareadme.com/
- https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-readable.md
- https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/
Top comments (7)
Your post is a nice concise summary of basics of what belongs in a project's README.
There's a really good GitHub repository that has a list of projects with especially good examples of high quality READMEs, as well as a list of tools and other resources related to READMEs. Check it out.
matiassingers / awesome-readme
A curated list of awesome READMEs
Awesome README
Elements in beautiful READMEs include, but are not limited to: images, screenshots, GIFs, text formatting, etc.
Examples
Thank you Vincent. I will check that out too! 😊
It's a good idea to include a readme of some type in any project - it doesn't need to be something you host on Github, and readmes aren't something Github invented.
Put them in your own private projects, put them in any library or module you write, put them in stuff you host elsewhere...
Keep them as Markdown or text, and the only thing you need to be careful of if you're using Github is that they use their own variant of Markdown. Ideally you should steer clear of using Github-specific Markdown so that it'll be readable when you fork or mirror it elsewhere.
Thank you, Ben. Noted.
How do I make an impressive GitHub profile README?
جلب الحبيب باسمه
readme.so/ is an awesome website for creating readmefiles
Thank you, Rachit! I'll check it out.