Skip to content

README: short, plain-language evidence cards generated from the outcome benchmark #14602

Closed

Description

@clubanderson

Problem

The v5 README is about 1,900 words across 23 sections. The outcomes block added in #14588 is correct but reads like a statistics report: grouped bars with confidence whiskers, n= labels, hatched cells, fractional-hour axes, and vocabulary (Wilson, median, mediated/unmediated) that a reader who is not a statistician cannot use. Most of the README's other sections are overview material that belongs in the docs.

Proposal

Rewrite the README as a short, evidence-first page built on the existing outcomebench generator so everything in it stays regenerable and drift-checked:

  • Prose budget: ≤ 600 words and ≤ 10 H2 sections, enforced by a test. Cards carry the evidence; prose is one or two flat sentences per section.
  • Plain-language cards (dark/light SVG via <picture>, real <text>, dashboard palette): one idea, one big number, one sentence, a small footer stating the base in words and the month. No statistical vocabulary in the README or on a card (enforced by a test). Comparisons that do not show a clear difference are not charted.
  • Sections in this order: scale line → Accuracy → Security → Cost → Also (consistency, readability, efficiency, speed) → How it works ladder → Run it (3 commands) → Learn more.
  • Minimum base for any production-count card in the README (configurable, default 200), separate from the report's n ≥ 10 threshold; small buckets stay in the benchmarks report only.
  • Stories: two real caught → fixed → merged pull requests from the review records, with timestamps taken from the evidence bundles.
  • Honesty: unfavorable or neutral comparisons stated in the same section; estimates labelled; self-run evaluations labelled; the report gains a "What the README shows and leaves out" section listing each card and why it was or was not drawn.
  • The detailed charts, intervals and methodology stay in src/docs/benchmarks/; the former README overview moves to src/docs/what-is-hive.md and the documentation map.

Activity

  1. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Oct 27, 2026
  2. github-actions commented on Oct 27, 2026

    @github-actions
    Contributor

    @clubanderson this issue was closed by @hivecommons-hive[bot] as completed.

    If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it — check your running version against the fix before concluding the fix failed.

    If you are still seeing the problem, comment /reopen and it will be reopened for you — you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions