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
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.mdfile and link to it
License (Optional)
- Add license information about your project. Not necessary if you have a
LICENSEfile
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
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
View my README.md guidelines
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! 💪
Top comments (0)