How to Create an informative README.md

#beginners #tutorial #markdown

Why A ReadMe Important?

Have you ever tried to put together a piece of furniture without the instructions? Even with the instructions, it's nearly impossible to build at times. Creating a project without a ReadMe file is like selling someone a bunch of boards and screws and telling them to try to piece it together on their own.

A ReadMe is a file that contains a set of pertinent information about the files you are looking at. You can usually find them in a repo or in the project directory. They can come in many styles and types, but the most common is a markdown file.

While working on my latest project, I thought it would be useful to create a template of a ReadMe file for myself that I can come back to in the future. I've seen plenty or ReadMes throughout my experience, and they are not all created equal. I tried to take note of the ones that looked nice and gave me all the information I needed. A couple things I noticed all of the good ones had in common were that they were:

easy to follow
easy to read
informative
interactive
and had images/demonstrations

Guidelines

All ReadMes will vary depending on the content of the information they are describing, but most ReadMe files should contain these elements.

Title
This one is pretty self explanatory. Your project/code should have a title. Putting the title at the top of your file in big letters should be the first thing you do.
Description
A description should follow the title. Explain what the files are, what they create, what a user should expect to see if they run the project or apply the methods described. If applicable, add a user-stories. What can the user do if they run this project? You can also write about your inspiration behind the project. Why was it worth your time to write these files? What were you trying to achieve or need you were trying to fulfill.
Demonstration
A demonstration is a vital part of the ReadMe file. It doesn't have to be complicated or fancy to be great. Something as simple as adding a couple of screenshots makes a huge difference in your ReadMe. If you are more ambitious however, you can create gifs that show your project in action. You can even record a video demonstrating your project and all the code you spent so much time creating.
How to Install Your Project
Different projects require different bundles and gems to begin working, so this part of your read me is vital. If you don't put any other information, at least put this info in your read me. Creating easy-to-follow, step-by-step instructions will ensure that the most inexperienced user will be able to spin up your project.
Credits
Often times, multiple people will be collaborating with you on your project, or you will be collaborating on theirs. In both cases, everybody who participated in the program should get credit. Adding relevant information such as Github and LinkedIn accounts can facilitate opportunities or give you a place to reach out with any questions.
Table of Contents (Optional)
A table of contents can be helpful if you have a very long ReadMe. For example, if you take a look at the ReadMe for Faker, it is extremely long. Creating a table of contents makes the ReadMe dynamic, user friendly and easy to read.
License (Optional)
This section will inform the user whether or not they need to purchase a license to use your material. It will let you know if you can use the code commercially, privately or both.
Badges (Optional)
Badges are a simple way of showing users metadata related to your project. Such as the amount of forks or if certain tests are failing. Shields is a library you can use to create them. They are dynamic, so you don't have to worry about updating this section.
How to Contribute to the Project (Optional)
If you are open to contributions, a ReadMe would be a great place to let people know how they can contribute. You can give guidelines on how someone can contribute and inform the user of the what is acceptable.
Project Status (Optional)
Writing a project status can allow people to offer to help if you are experiencing a slump in regards to the project. It can also inform people whether something is in the works, or if they can expect a fully working product.

ReadeMe Template

# Project Title

Description of your project.

## User Stories

* A user will be able to do this thing
    * and this thing
* This thing too

# Demo

Put images ![image name](image Url), vidoes, and anything else needed to demo your project.


## Setup

Instructions on setup go here


## Credit

Created by: Name Here
Created by: Name Here
Created by: Name Here
[GitHub](GitHub Profile)
[LinkedIn](LinkedIn Profile)
email, etc...