This article will explore possible items to include your Git repo README file. We will discuss several items that we can include in a README and when to include them.
What is a README?
A README file is a text file that explains a project to new user. It helps users quickly understand where to find information on the project such as brief description of your project, how to install/fork it and/or how to use your code. READMEs live in the top level directory of your repo in GitHub, Bitbucket or GitLab.
Why should I make a README?
A great README will facilitate easy comprehension, fast utilization and numerous contributions to your project. A poor README will lead to endless frustration and avoidance of your project. Lots of great repos have great READMEs. It’s also good documentation practice- READMEs are perfect for capturing updates on your project in one place.
How do I write a README?
You can write a README using any text editor e.g. vim, Notepad, Sublime, Notepad++ or Atom, because it can be written in any text file (e.g. .RST or .TXT). However, Markdown (.MD) is the most common file format as it allows for text formatting that makes the README easy to read. Some text editors have plugins for previewing the README while writing it. For testing your Markdown input using an editable template, you can check out https://www.makeareadme.com/.
What goes into a README?
Below I present some examples of what can go into a README. Remember that many items are optional and dependent on the type of project, so feel free to skip unnecessary items as long your documentation is complete. The left panel has the raw Markdown input and the right panel shows the rendered result as you would see in it on GitHub.
You can download the entire README template file below:
Helpful Links
- Various README templates & links on guidance: https://github.com/matiassingers/awesome-readme
- Repo Folder Structure Convention for various programming languages/applications: https://github.com/kriasoft/Folder-Structure-Conventions/blob/master/README.md
- Markdown Reference Help & tutorials: https://commonmark.org/help/