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