We had a batch of project pages whose descriptions were the repository's own GitHub text, some of them in Chinese, and 2,113 of them needed rewriting in English. This is what writing 300 of them taught us about descriptions.
A description is not a summary
The first thing we got wrong was trying to summarise the README. A summary of a README is a worse README. The description on a project page has a different job: it is one or two sentences that tell somebody scanning a list of forty projects what this thing is, and then the body does the rest.
So the shape became: what it is, in one clause, then the one thing that makes it different from its obvious neighbour. Not the architecture, not the feature list, not the history.
The second sentence is the hard one
The first sentence is usually available in the repository's own description or the first line of the README. The second sentence is where the work is, because it is where the comparison lives.
"We are a self-hosted PaaS" is the first sentence of forty projects. "It puts a web UI and automatic certificates in front of a compose file" is the second sentence that tells you whether this is the one you want.
We wrote the second sentence as an explicit comparison to the obvious alternative — the thing someone would otherwise pick — and the pages got noticeably more useful.
What we stopped doing
Listing features. The feature list is on the page, further down, and it is the same list the README has. Two lists of the same features is worse than one.
Writing about the technology. "A Rust implementation of a vector database" tells you nothing about whether you want it. The implementation language is already in the fact block.
Claiming what we did not check. Every claim in a description has to come from the repository, the licence file, or our own pages. We have a rule that a description may not contain a number we did not compute.
The part that surprised us
The same sentence shapes kept working across completely different projects, which is a sign that the problem is not about the projects. It is about the reader, who is scanning a list and needs the difference, not the description.