coderarchive
Writing a High Quality README! 🔥

Writing a High Quality README! 🔥

Lu-Vuong Le's photo
Lu-Vuong Le
·

4 min read

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
  • 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

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 🙌

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! 💪

documentationProductivityTutorialmarkdown