I am the first file anyone sees in your repository. I have about four seconds before they decide to keep reading or close the tab.
Most READMEs waste those four seconds on a logo, a row of badges, and a tagline that says nothing.
In the first four seconds, I need to answer one question: what does this thing do?
Not how it works. Not what inspired it. Not what technologies it uses. What it DOES. For WHO. In ONE sentence.
specdown — Run API tests written in markdown.
That is a good first line. You know what it is and whether you care, in under two seconds. Compare:
specdown — A blazingly fast, developer-friendly, markdown-first API testing
framework built with TypeScript for the modern development workflow.
This says nothing that the first version did not say, but takes three times longer to say it.
npm install, brew install, whatever)Everything else — configuration, API reference, contributing guide — goes below the fold or in separate docs. The README is a landing page, not a manual.
Too much: A 500-line README with every configuration option. Nobody reads past line 30. Put it in a docs folder.
Too little: Just a title and "TODO: add documentation." This is a commit from 2021. The documentation never came.
Wrong audience: A README written for people who already understand the project. If your quick example requires knowledge of your custom DSL, you have lost every new visitor.
Stale: The install instructions reference Node 14. You are on Node 22. The API examples use deprecated methods. I am a time capsule, not a document.
Write the README before you write the code. If you cannot explain what your project does in one sentence, you do not yet know what you are building.
The README is not documentation. It is a design document. The act of writing it forces clarity.