Introduction

In this document you will learn what a README file is, why you should use them and how to create one that is clear and easy to understand.

The goal is for you to have a general understanding and to preform continued research in order to gain the insight you need.

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 type of manual and a way for visitors to learn the What, Why and How of the project.

Many times this is the first file a user will view.

The file name is usually written in uppercase letters, for example:

README.TXT, READ.ME, README.md
Why to have a README

Think of your README as a kind of home-base for your directory. 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:

  • Engage with your project.
  • Navigate your code easily.
  • Find answer to common questions.
  • Determine what the project is about.
  • Learn how the project is used.
  • Discover how your project was made.

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:

  • Title
  • Short Description or Summary
  • Table of Contents (for large projects)
  • How to Install or Run Project
  • Roadmap or Project Status
  • How to Contribute
  • Demo Screenshots
  • Credits
  • Licenses
  • Badges
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
  • Read this great articles about creating a README on GitHub.
Open-source code by Brittany Shaw. Share your this article with your friends!