Reader votes and ratings

A Papyrus publication is steered by its editors. This feature lets the readers steer it too. A reader signs in, picks a public handle, and can upvote an item, say they used it, and rate it on the dimensions the publication chooses, such as how real, useful, notable or novel it is. Editors rate with the same controls, and their ratings are kept apart from the readers' so a page can show both.

The feature is built and tested, and the identity it needs is in place: the account service gives each site its own private identifier for a reader. Reader sign-in turns on one site at a time, when that site enables the feature. Nothing here says that any site has it running today.

What a reader sees

• A Sign in link in the header. After sign-in, the reader picks a handle once, and the header then shows the handle, a karma number and a Sign out button.
• An upvote button with a count, an "I used it" button with a count, and a one-to-five rating for each of the publication's dimensions.
• A line that says how fresh the numbers are, such as "Updated 5 min ago".
• A ranked list of the front, rising or newest items, as a numbered list with each item's title, section and score, upvotes or age, and the word "Pending" on a link a reader has submitted that is still waiting.

Every state is written in words as well as styled, the buttons announce whether they are pressed, and everything works from the keyboard. Until sign-in is open for the site, the controls are disabled and say "Reader sign-in is not open yet".

How the numbers reach a static page

The public site stays static. Votes and ratings go to a small authenticated API in the site's CMS app, which checks the sign-in, the request's origin and its size, limits how often one reader can act, and stores the result. A background run then writes a few small JSON files into the site's bucket: the numbers for each item, the ranked boards, the title and link of each ranked entry, and the readers with the most karma. The page components read those files when the page loads and again every minute while the tab is visible, and they show the reader's own votes immediately.

The run starts shortly after a vote, at most once a minute, and the publication can add a schedule that rebuilds the numbers every few hours so that time decay and the Rising board stay current.

Privacy

A reader is known to a publication only by an opaque identifier that is different for every site, so two publications cannot tell that the same person reads both. 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 test renders the public files and the projected pages of a sample site and fails if any of those appear.

What a publication sets

The publication decides its own rating dimensions, how many votes and ratings one reader may make in an hour (new accounts get a third of that), the handles nobody may take, how karma is counted, and how the ranked boards weigh editors, readers and age. These are settings in the site's configuration, not code.

Ranking and karma

The front board starts from the editors' ratings, reduced as an item ages, and blends in the readers' ratings once enough readers have rated. The Rising board counts upvotes from the last few hours. How editor and reader scores should combine is still being explored, so the files carry each score's raw parts and the formula can change without moving any data. Karma counts upvotes and used-it reports that a reader's submissions receive from others. A site that has not enabled submissions has no karma to count, so everyone's is zero.

Readers can also submit links, which editors moderate, and comment on stories, explaining their ratings.

The details for people who run a publication are in the Papyrus repository, in docs/reader-steering.md.