How to create a README.md file

image via KDnuggets

So, you have this super fantastic project on GitHub that you would like to showcase to your friends, colleagues, future employers and even to use as a reference to your future self. Well, what would you imagine is one of the most important files that should be consistently found in each and every repository that you have on GitHub? *Spoiler Alert* It’s in the title of this article: the README.md file. I know, you’re like, “How is this simple file going to exhibit any of my technical skills, much less impress the gatekeepers of my dream Developer job?”

In this blog post we will not only get down to the bottom of the importance of the README.md file, I will also provide you with a boilerplate template for a README.md file. You can then use this file in your past, present, and future GitHub repositories.

Why should a README.md file be included in a project?

Just as the name implies, “readme,” this is one of the very first files that anyone is going to read and review in order to figure out:

• what your project is all about,
• how to use it,
• why it is important to you,
• who this project was created for,
• where key components reside within the project, and
• how this project may or may not benefit them in their search.

Essentially this one document can make or break someone’s interest in both reviewing and verifying that your code is indeed valid. Sure, quality code is law, but you did not do all of that amazing work just for a code review. You completed a project to see it live and in action.

Who is the README.md file created for in a project?

As mentioned earlier, the README.md file is created for your friends, colleagues, future employers and even to use as a reference to your future self. Basically any and everyone that you send to your GitHub that will look at your project in hopes to learn from, contribute to, benefit from or use on their projects.

When is it proper/essential to create a README.md file for a project?

Since the README.md file is one of the first files reviewed by yourself and others within your project, it should also be one of the first files created. This will allow you to add key and critical facts as your project grows. Essentially this will allow onlookers and contributors to have the most up-to-date information about your project to efficiently review and consume.

What should be included in the README.md file for the project?

A README.md file can be as simple or robust as you would like. However, here are the key and traditional sections to be included:

• Name of project
• Project Overview — What is your project all about? Who was it created for? Why is it important to you? When was it created? Where can we find it live or the official documentation? How does one go about using it live or within their own project?
• Configuration instructions — Computer and Software configurations are recommended to achieve optimum performance based on operating systems such as Windows, iOS, Android, and mobile.
• Installation instructions — This will include, but is not limited to, any packages and dependencies required to make your project function.
• Operating instructions — “What is this? Where does this go?” Now is the time to demystify any assumptions around how to use your project.
• A list of files included — Contingent upon how large your source code is, you may opt to not include the file tree, however you can still explain how to traverse through your code. For example, how is your code modularized? Did you use the MVC (Model, View, Controller) method? Did you use a Router system? Just a few questions to consider when detailing your file structure.
• Copyright and licensing information — In order to let others know what they can and cannot do with your code, it is important to include a software license in your project. If you opt out of using a license then the default copyright laws will apply and you will retain all rights to your source code and no one may reproduce, distribute, or create derivative works from your work. Hence the reason licenses are critical and highly recommended for open source projects.
• Contact information for the distributor or programmer — Name, email, social media links, and any other helpful ways of getting in contact with you or members of your team.
• Known bugs — This is the perfect place to put tickets of known issues that you are actively working on or have on backlog. Speaking of backlog, if your project is open source, this is will allow potential contributors an opportunity to review incomplete features.
• Troubleshooting — In this section you will be able to highlight how your users can become troubleshooting masters for common issues encountered on your project.
• Credits and acknowledgments — Who were the contributing authors on the project, whose code did you reference, which tutorials did you watch that help you bring this project to fruition? Sharing is caring and all praises are due for those that have helped no matter how small the contribution.
• A changelog (usually for programmers) — A changelog is a chronological list of all notable changes made to a project such as: records of changes such as bug fixes, new features, improvements, new frameworks or libraries used, and etc.
• A news section (usually for users) — If your project is live and in production and you are receiving feedback from users, this is a great place to let them know, “Hey, we hear you, we appreciate you, and because of your feedback here are the most recent changes, updates, and new features made.”

Where should the README.md file be located in the project?

The README.md file should be easy to find and is commonly found in the same place within most projects industry wide. This place is in the top-most directory known as the root directory which is in the hierarchy of a project file system. Because of this, GitHub will recognize the README.md file and display the text, making it the focal point of your repository.

How should the layout of a README.md file be structured for a project?

Link to gist for template

Note: READMEs can be written as .txt, .me, or .md files. In this blogpost I referenced the most common file type used, .md also known as Markdown.

For all of the bells and whistles on how to write in this super simple markup language please review the following resource: Markdown Cheatsheet Online and Markdown Cheatsheet

Also, if you find a markdown file that you like, you can look at the raw file and copy the formatting to your liking.

If you found anything in this article helpful, please show how much with a round of applause (claps) :)