The editorial gate: what a project page needs before it can be published

Show & TellValerie3 replies

ValerieRegular#1

Every project page on this site goes through the same gate before it is published, and the gate is the reason the pages can be read as fact rather than as opinion. It is worth writing down what it checks, because a lot of it is not obvious from the outside.

What has to be true

Every fact has a source. A star count comes from the daily snapshot. A licence comes from the licence file. A maintenance state is arithmetic on the last push date. A number we computed ourselves says so, in the text, and says how it was computed. There is no category of fact on a project page that is "from memory".

Every claim is checked against the repository. Not against a blog post about the project, not against a comparison, not against the project's own marketing page. The README, the licence file, the compose file, the issue tracker.

The summary is ours and says so. The one-line description at the top is the repository's own text, and where we rewrote it, the page shows both. The body is written by us and is clearly ours.

The licence is read, not detected. The SPDX identifier in the header comes from GitHub's detector. The claim in the body — that this is Apache 2.0 with two conditions, or that this is a business source licence with a change date — comes from a person reading the file.

What the gate rejects

A page whose numbers cannot be traced. A page that describes a project it has not read the README of. A page that recommends something for a use case the project does not support. And a page that is thin: a project page with three paragraphs and no fact is a page that exists to take up a URL.

Why the gate is separate from the writing

Because the interesting failure is not a wrong sentence. It is a page that reads well and is subtly wrong, and that is exactly the kind of page a writer cannot check, because the writer is the one who wrote it.

So the writer and the checker are different people, and the checker is not asked whether the page is good. The checker is asked whether every claim on it can be traced, and whether the licence paragraph matches the file.

It is a slow process. It is also the reason the pages can be used to make a decision about a dependency.

3 replies

Hysen YanStaff#2

The separation between the writer and the checker is the load-bearing part, and it is the part that costs.

The same person can write an excellent page and miss a wrong version number in it, because reading your own sentence is not the same as reading it as a stranger.

EricMember#3

In reply to Hysen Yan (#2)

The "a page that reads well and is subtly wrong" description is the exact failure mode I would expect, and the traceability rule is what catches it.

If every claim can be traced to a file in the repository, then the check is mechanical. If a claim cannot be traced, it is either wrong or it is ours, and in both cases somebody has to look at it.

ValerieAuthorRegular#4

In reply to Eric (#3)

Both are right, and the second one is a neat reformulation: the check is not "is this page correct" but "is every sentence on it either traceable or flagged as ours".

That is a much smaller question to answer, and it is the one the checker is actually equipped to answer.