Skip to content

docs: add a help page for reading the results page - #1541

Open
masiarek wants to merge 1 commit into
Equal-Vote:mainfrom
masiarek:docs/results-page
Open

masiarek wants to merge 1 commit into
Equal-Vote:mainfrom
masiarek:docs/results-page

Conversation

@masiarek

Copy link
Copy Markdown
Collaborator

Description

Adds a help page, Reading Your Results (docs/help/reading_your_results.md), that walks a voter through a results page from top to bottom:

  • The headline — what the PRELIMINARY label means (links to Preliminary Results) and what the voter count counts (ballots in the tally; a ballot scoring everyone the same is an abstention).
  • The two round charts — the Scoring Round, the Automatic Runoff, Equal Support, and the majority-threshold line with its half-of-voters-with-a-preference denominator, which is the number readers most often misread.
  • Race Details — the Scores Table and the Runoff Table's two percent columns (% Runoff Votes vs % Between Finalists) and which one decides the race.
  • Stats for Nerds — one short section per panel (Tabulation Steps, Head-to-Head Matchups, Distribution of Equal Support, Average Supporter Profile), each naming the denominator that panel uses, since that is where most "that can't be right" moments come from.

Notes for reviewers:

  • The scoring-round-vs-runoff divergence gets one paragraph here on purpose — docs: add a help page for why the highest score doesn't always win #1528 proposes a dedicated page for that topic, so this page doesn't duplicate it (and doesn't link it, since it isn't on main yet; happy to add a link if docs: add a help page for why the highest score doesn't always win #1528 merges first).
  • The page is written to work without images, but screenshots of a real results page (the round charts, a Head-to-Head bar, a Supporter Profile) would improve it — I've left those to whatever house style you prefer.
  • Verified with a local github-pages Jekyll build: the page renders, appears in the sidebar under BetterVoting Documentation, and all internal links resolve (.md form, targets all on main).

Screenshots / Videos (frontend only)

N/A — docs only.

Related Issues

Complements #1528 (dedicated page on why the highest score doesn't always win).

Walk a voter through a BetterVoting results page top to bottom: the
headline (what "preliminary" and the voter count mean), the two round
charts (including the majority-threshold line and its voters-with-a-
preference denominator), the Race Details tables and their two percent
columns, and each Stats for Nerds panel (Tabulation Steps, Head-to-Head
Matchups, Distribution of Equal Support, Average Supporter Profile),
with the denominator each one uses.

Kept deliberately shorter than a full walkthrough: the scoring-round-
vs-runoff divergence gets one paragraph here, since PR Equal-Vote#1528 proposes
a dedicated page for it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@netlify

netlify Bot commented Aug 17, 2026

Copy link
Copy Markdown

Deploy Preview for bettervoting ready!

Name Link
🔨 Latest commit 5e991b6
🔍 Latest deploy log https://app.netlify.com/projects/bettervoting/deploys/6a8267861833e100080429b1
😎 Deploy Preview https://deploy-preview-1541--bettervoting.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

@masiarek, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 2 minutes

Limit details: You’ve used all 1 included review currently available under your plan.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ef35853b-bdc4-4d84-8cc4-746d547f20d3

📥 Commits

Reviewing files that changed from the base of the PR and between 7bc75a8 and 5e991b6.

📒 Files selected for processing (1)
  • docs/help/reading_your_results.md

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant