12/20/2021
How to Properly Write a GitHub ReadMe
Every GitHub repository needs a good ReadMe. ReadMes help viewers figure out what your code does, how to use it, and how you made it. Unfortunately, it is very common to see sub-par ReadMes that provide little to no information about the code base. If you are struggling with writing ReadMes, then this article is for you. In all honesty, this article is for me too.
In this article I will go over how to write ReadMes for two types of projects:
1. Projects that won't be frequently updated
2. Projects that will be frequently updated
Projects that won't be frequently updated
If you are coding a project that you don't plan on updating after committing it to its repository, then here are the sections you should put in the ReadMe:
- Description
- Tell the viewer what this repository does and how to use it (run commands, how to compile, etc.)
- Technologies Used
- Make a note of all the technologies (languages, libraries, etc.) that you used to make your project
- Notable Features
- Talk about the features of this program: how everything works together and what sets it apart from others that may be like it
- My Role (Optional)
- If you made this as part of a team, describe the role you had in creating this project
- Project Difficulties (Optional)
- Talk about the challenges you had during the process of programming your project and how you overcame them.
- What I Learned
- If you used a library or programming language for the first time, talk about what features in those that you learned and how it helped you understand how to use said library or programming language
Projects that will be frequently updated
If you plan on consistently updating your project, you will need to add a few more things to the above list of sections:
- Changelog
- Make a note of the current version your program is in (and rememebr to update it every time there is a change. Then explain the most recent changes and updates to your code
- Known Bugs
- Make a checklist of all the known bugs in the program and check them off once they are successfully squashed
- Upcoming Updates
- Make a checklist of all the changes you want to make to your code in the future and update it each time you add one of the changes
In my opinion, those are the most important sections that need to be in every ReadMe. I hope you found this post helpful!
