Writing 300 project descriptions in one sitting: what repeated itself

Show & TellDaisy3 replies

DaisyRegular#1

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.

3 replies

EdwardMember#2

The comparison-to-the-obvious-alternative rule is the one I would keep and the one I would apply to every page, not only the descriptions.

A reader arriving at a project page has usually already decided between two or three projects and is checking whether this is the one. A description that does not name the difference is a description that makes them do the comparison themselves, elsewhere.

RonnyMember#3

In reply to Edward (#2)

"Two lists of the same features is worse than one" is the part that took me longest to accept, because the instinct is to give the reader everything on the page they are looking at.

But they are not looking at the page yet. They are looking at a list, and the list needs the difference. The features are for the reader who has already chosen.

DaisyAuthorRegular#4

In reply to Ronny (#3)

Both are right, and I would add the practical consequence: a description with no comparison is also a description that is impossible to write consistently across forty projects, because the same sentence shape works for some categories and does not work for others.

Writing "it does X instead of Y" forces the sentence to be about the choice the reader is making, and the choice exists in every category.

More in Show & Tell