DEV Community

Cover image for Notes on GitHub READMEs
Mfon.
Mfon.

Posted on

Notes on GitHub READMEs

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.

basic usage on github readme

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.

GitHub License

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

  1. https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
  2. https://www.makeareadme.com/
  3. https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-readable.md
  4. https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/

Top comments (7)

Collapse
 
cicirello profile image
Vincent A. Cicirello

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.

GitHub logo matiassingers / awesome-readme

A curated list of awesome READMEs

Awesome README Awesome

A curated list of awesome READMEs

Elements in beautiful READMEs include, but are not limited to: images, screenshots, GIFs, text formatting, etc.

Examples

  • ai/size-limit - Project logo, clear description, screenshot, step-by-step installing instructions.
  • aimeos/aimeos-typo3 - Project logo. Clear description of what the project does. Demo screenshot. TOC for easy navigation. Easy installation and setup sections with screenshots. Links for further reading.
  • ajeetdsouza/zoxide - Badges, project GIF, concise description, quick links, stepwise installation instructions.
  • alichtman/shallow-backup - Clear description of what the project does. GIF Demo. TOC for easy navigation. Badges. Links for further reading. Simple install instructions.
  • alichtman/stronghold - Project logo. Clear description of what the project does. GIF Demo. TOC for easy navigation. Badges. Links for further reading. Simple install instructions.
  • amitmerchant1990/electron-markdownify - Project logo. Minimalist description of what it is. GIF demo of the project. Key features. How to install guide. Credits.
  • amplication/amplication - Clear project logo…
Collapse
 
themfon profile image
Mfon.

Thank you Vincent. I will check that out too! 😊

Collapse
 
moopet profile image
Ben Sinclair

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.

Collapse
 
themfon profile image
Mfon.

Thank you, Ben. Noted.

Collapse
 
kerriavalos profile image
KerriAvalos

How do I make an impressive GitHub profile README?
جلب الحبيب باسمه

Collapse
 
dilutewater profile image
Rachit Khurana

readme.so/ is an awesome website for creating readmefiles

Collapse
 
themfon profile image
Mfon.

Thank you, Rachit! I'll check it out.