In this document you will learn what a README file is, why we use them and how to create one that is clear and easy to understand.
Introduction
In this document you will learn what a README file is, why we use them and how to create one that is clear and easy to understand.
What is a README file?
A README file is a text file that contains information for all other files within a directory. The README file serves as a form of documentation and a way for visitors to learn the What, Why and How of the project.
The file name is usually written in uppercase letters, for example: README.TXT, READ.ME, README.md
Why to have a README?
README files are the first file in your project. This is the place for you to include detailed documentation that will allow your project to be easily navigated. Why? The easier your project is to navigate the more engagement you will receive.
The README file will allow visitors to:
It is encouraged that ever project include a detailed README file. Make a routine of creating a README file with every project you create.
The first thing you should create for every project is your README file.
What to include?
Every README file should include important documentation. This can include anything the creator chooses but the most important items are a Title, Description and How To.
The following are recommended:
To make sure your visitor can navigate your project have your README organized and easy to understand. How to format Typically a README is created in text file format with markdown. This will allow creativity in a clean minimalist format.
While you can freehand the creation of your README there are applications out there to help maximize your time and organization.
For example: https://www.mkdocs.org/ is a great site.
Your README can be simple and minimalistic! Just make sure to include the important details.
Extra Credit 🎇