Every Project Needs a Good README

The most important type of documentation for a Project is its README

Here’s what Top class READMEs contain 🧵👇

1. Project Title + High Level Summary

Tell what the project is and what it does

  • Consider the reader to be non-technical
  • Use simple language
  • Keep it brief

2. A Showcase Section

Show what your project does. Visually.

  • Embed a short Video showing your product
  • Show Before/After Images
  • Can you point to a DEMO instance?

3. A Getting Started

  • list pre-requisites and required dependencies
  • List commands on how to install it with a package manager
  • Show examples of how to use it
  • Add download links for the latest release

4. A Build Section

  • What commands are needed to build the entire thing?
  • Which ports is the application running on?
  • Point to HOW TO documentation

5. Contribution Documentation

  • Each proper project needs a software license
  • If your project accepts MRs, provide a Contribution Guideline
  • Add Templates forc reating Issues that contain checklists

6. Optional: Add Badges

Indicate the current status of your Project

  • by adding a Badge indicating the current CI status
  • show your projects key metrics
  • indicate your license

A Project without a half-descent README is not worth looking at.

Writing one does not require much effort.

However increases your Projects value ten fold.

First published on @ederbit: Here’s what Top class READMEs contain