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