Writing a High Quality README! 🔥
Tags: tutorial, webdev, productivity, documentation
Published: 2020-10-15 09:10:05

# How **good** are your README files?

Many developers know this file is important when creating project but 

- **how well do you write your README files?** 
- **Do you know how you should go about writing a high quality README?**

There is **no one right way** to write one but there is a very wrong way which is to not have a README at all. I've seen many projects with a very minimal README or none at all 😟 

So I'm going to give you my own **opinion/guidelines** from my experience of what a quality README should be but first let's go over why we need a good one in the first place.

# You **need** a good README because it: 

- Will be the first file the user will see. A good README engages the user with the project 
- Explains and showcases what your application does
- Allows you to clearly explain how to run your application, test or contribute
- Justify technology stack used
- Stand out from other developers and projects

# Here's my guidelines of **what** to include

#### Project Title

- Your application or project name should be displayed first and foremost. Let everyone know what the name of the amazing project you're working on is! 😃

#### Badges
- Badges make your README a lot more professional and really shows other developers that you know what you're doing! You can find badges all over but a good place to start is: [shields.io](https://shields.io/)

#### Screenshot / GIF of the application (Demo)
- This one is self explanatory but showing your application in action is **highly** recommended. Using a **GIF** is much more preferred as from my experience it's more pleasing to see the application in real time than screenshots and will grab the attention of the person viewing your project

#### Application Description (One Line)
- A short description or paragraph of your application/project

#### Table of Contents
- If your README is lengthy then it is **always** a good idea to include a table of contents section for easy navigation

#### Application / Deployed Links
- Include a link to your deployed application. You can also put in other links like a Kanban board for example

#### Technology Stack
- People are often curious about what tech stack you have used and even more so if they want to contribute. This is a good section to include in order to demonstrate your chosen tech stack. You can use a table format to make things neater

#### Features (Optional)
- Now this is optional but if your application is large with many features, you can show this off with this section and list as many features as you want 💯

#### Installation
- Include steps to install your app for development and production. Provide clear step by step instructions to make it easy for other developers

#### Configuration Setup
- Alongside installation, you may have some configuration files that are necessary to setup for each person. Add notes here about config options and what they need to change

#### Usage
- How does someone use your application? Add instructions here to run the application after installing and configuration is complete

#### Tests
- Testing is important in any application! Explain your testing methods and provide instructions on how to run them. If tests need seed data, be sure to include that as well

#### Collaborators
- If other people have contributed to your project, make sure you provide a section for collaborators to give them credit where it is due! A good way to do this is in a table format with their name and link to their GitHub page

#### Contributing Instructions
- If your project is open source, provide instructions on how people can contribute according to the guidelines you set to ensure consistency. A good way to do this is to create a `CONTRIBUTING.md` file and link to it 

#### License (Optional)
- Add license information about your project. Not necessary if you have a `LICENSE` file

#### Contact Information (Optional)
- Provide any contact information such as email if you would like

#### Note: Make use of emojis! You don't have to overdo it but in my opinion they make it more pleasing to view 😃

# **Examples** of good READMEs
- [Awesome README List](https://github.com/matiassingers/awesome-readme)
- [Visual Studio Code](https://github.com/microsoft/vscode)
- [Release It](https://github.com/release-it/release-it)

#### Some Templates/Guidelines

I've created some GitHub gists below with guidelines I use for both a README.md and a CONTRIBUTING.md to help out myself and everyone 🙌

- **View my [CONTRIBUTING.md guidelines](https://gist.github.com/luvuong-le/714407ccd98dfe820bd7a3bdfaec5e04)**

- **View my [README.md guidelines](https://gist.github.com/luvuong-le/ec9eaa582c34b1403d1b811fbc5c51d7)**

---

I hope this has been useful to everyone! READMEs are very important for other people and act as a sort of documentation as well. Now that you know how to write better READMEs, get out there and create awesome ones! 💪