Comments as steering

A rating says how a reader felt. A comment says why. Papyrus treats the reason as a signal: when a reader rates a story and explains the rating, the explanation travels next to the vote it explains, so the people and the Cyclotrons that steer the publication can see both.

The feature is built and tested. It turns on one site at a time, when that site enables the reader features; nothing here says that any site has it running today.

What a reader can do

• Comment on a story or on a submitted link. A comment is plain text, up to 2,000 characters and three links. It is shown as written; markup is never run.
• Reply to a comment, one level deep.
• Edit their own comment for ten minutes, and delete it at any time. A deleted comment leaves a short "This comment was removed" line so that replies keep their place, and only while it has replies.
• Explain a rating. Right after rating a dimension, the reader is asked "Why? (optional, public)". The answer is posted as a comment that carries the rating it explains. The site checks that it is the reader's own current rating, so nobody can attach a reason to a vote that was never cast.
• Report a comment that breaks the rules. A moderator decides what happens to it; see Reader submissions and moderation.

A reader can post thirty comments an hour, and a new account a third of that. Every state is written in words, the controls work from the keyboard, and a comment being typed survives the page refreshing its numbers.

How comments reach a static page

The public site stays static. Comments go to the same small authenticated API as votes, which checks the sign-in, the request's origin and its size and the reader's limits. A background run then writes one small file for each story that has comments, and a count into the numbers file. The page reads its file when it loads and again every minute while the tab is visible, and it shows the reader's own comment at once. Hidden and deleted comments disappear from the next file.

How a comment steers

Papyrus keeps the people who edit a publication apart from the people who read it. Editors' ratings and decisions are one signal. Reader comments are another, kept separate and labelled by the reader's public id:

• A command, papyrus reader feedback export, writes every comment as one line of JSON: the text, the story it is about, the rating it explains and when it was written, attributed by the reader's random public id. It can ask only for what changed since the last export.
• A comment that was later hidden or deleted comes out once more as a retraction, so a consumer that already took the text can drop it.
• Nothing calls the learning system while a reader is waiting. The Cyclotron loop pulls the export when it is ready.

A reader's rating on its own is never made public next to their name, and the public comment file does not carry the rating a comment explains.

Privacy

The public files carry a random reader id and the handle the reader chose, never an email address, a name or the identifier the site uses internally; a comment cannot contain an email address. A test renders the public files and fails if any identifying value appears.

The details for people who run a publication are in the Papyrus repository, in docs/reader-steering.md. See also Reader votes and ratings.