What Makes a Great README? The 14-Point Checklist Every Developer Needs

Your README is your package's cover letter, pitch deck, and user manual — all in one file. Most of them are terrible. Here's how to fix yours. There is a brutally honest moment every developer experiences: you land on an npm package that looks like it might solve your exact problem, you click the GitHub link, and the README is four lines. A package name. "Installation: npm install ". A single code example. No explanation of what edge cases it handles, no mention of whether it works with your Node version, no indication the project is even maintained. You close the tab. The package had 40,000 weekly downloads and might have been exactly what you needed. But the README failed the five-second test, and you moved on. This happens thousands of times a day across the open source ecosystem. Great code disappears into obscurity because no one invested 90 minutes in documentation that would have driven adoption for years. I wrote a tool called readme-score to automate README quality audits — a