What changes in a README as a project grows
5 min read
A README is not a document. It is a filter, and what it filters for changes as a project grows.
We measured 2,069 public GitHub READMEs, sampled in a grid of seven star bands by ten languages, and asked a narrow question: which structural elements become more common as a project gets bigger, and which do not.
The point of asking it that way is that it separates two things people usually conflate. "Successful projects have X" is cheap. "X is 65 points more common at the top than the bottom" is a measurement, and it comes with a denominator.
Everything below is observational. A cross-sectional study cannot tell you that adding a documentation link causes growth, and we are not going to pretend otherwise. What it can tell you is what the gap looks like.
The four things that separate the bands
| Element | 0 to 10 stars | Over 5,000 stars |
|---|---|---|
| Link to documentation | 11% | 76% |
| Contributing guidance | 12% | 65% |
| Screenshot or image (not a badge) | 20% | 61% |
| Installation instructions | 41% | 73% |
A documentation link is the single widest gap in the study: 11% at the bottom, 76% at the top, a 65-point spread. That is not subtle, and it is not expensive to close.
The screenshot figure is worth a note on method. We classify badges separately from content images, and we also exclude logos, banners, sponsor artwork, avatar collages and star-history charts. If you count every image, almost every README "has one" and the measurement becomes meaningless. What we are counting is an image that shows the project: a screenshot, a diagram, a terminal recording.
The thing that gets worse
| Element | 0 to 10 stars | Over 5,000 stars |
|---|---|---|
| Explains itself within the first 400 characters | 84% | 47% |
This one runs against intuition, which is why it is the most interesting line in the table. Small projects say what they are almost immediately. The median small README reaches its first line of actual explanation after 38 characters. The median large one takes 427.
The caveat has to travel with the finding: large projects accumulate chrome. Logos, centred HTML headers, badge rows, language switchers, sponsor tables. Our measurement counts characters before the first explanatory prose line, so it cannot separate "writes worse" from "has more furniture in front of the writing". Both readings are interesting. The data does not choose between them.
What it does suggest is that the furniture has a cost, and that the cost is paid by exactly the reader you most want to keep: the one who arrived from a link, has four tabs open, and is deciding whether to close yours.
The thing that barely moves
| Element | 0 to 10 stars | Over 5,000 stars |
|---|---|---|
| Quick start or usage example | 54% | 59% |
Five points. Essentially flat. A usage example is roughly as likely in a project with nine stars as in one with fifty thousand.
That makes it the least useful element for distinguishing projects, and arguably the most useful for a maintainer, because the flatness means nobody is winning on it. There is no established norm you are failing to meet.
Length is the wrong lever
Median README length rises from 247 words in the bottom half of the sample to 848 words in the top decile. It would be easy to read that as "write more".
The more useful number is sections. Of a fixed thirteen-item checklist, the median bottom-half README has 2 and the median top-decile README has 5. Length is a side effect of covering more ground, not the thing itself. A 900-word README that covers two topics is not closer to the top decile than a 300-word one that covers five.
What almost nobody does
A section identifying who the project is for is absent from 92.6% of the sample, and present in only 15% even above 5,000 stars.
This is the one element that does not improve much with popularity, which makes it the clearest actionable gap rather than a correlate of growth. Everyone writes what their project does. Almost nobody writes who should care.
We want to be careful with this number, because it is the one our own measurement is weakest on. The detector finds a who-it-is-for section with 67% recall against hand-scored labels, which means the true rate is somewhat higher than 7.4% present. The honest claim is directional: roughly one README in ten says who it is for. The specific percentage is not something we can pin down, and an earlier version of this study put it at 99% absent before we measured our own instrument and found it was missing "Why X?" sections.
How to use this
Four of these are a checklist, and it is a short one. A documentation link, contributing guidance, an image that shows the thing, and an install command. Those are the four with real gradients, and none of them takes an afternoon.
The fifth is the one worth more thought: say who it is for, above the fold, in a sentence. Almost nobody does, at any size.
The full study, every figure with its denominator, the complete list of limitations, and the validation of the detectors against 360 hand-scored READMEs are published at the README Benchmark. If you want to see where your own README sits in these distributions, the grader runs the same code over any public repository.