Writing a Good README

Must Have

Project name + one-line description — what it does, not how it works

Installation instructions — assume a fresh machine

Usage example — ideally copy-pasteable code

License — MIT, Apache 2.0, or whatever fits; just pick one

Should Have

Badges — build status, npm version, test coverage

Contributing guide — even a short one reduces friction

Screenshots or GIFs — worth 1000 words of documentation

API reference — at least for the public-facing methods

Nice to Have

Architecture overview — a diagram or short paragraph

FAQ section for common gotchas

Changelog — or link to GitHub releases

Anti-patterns

Wall of text with no headings or sections

Outdated screenshots from 3 versions ago

"TODO" sections left in the README for months