Skip to content

Simplify bilingual READMEs while preserving generated results and implementation guidance #74

Closed

Description

@tappe9

Priority and purpose

P3 — usability and maintainability improvement. Make the project understandable on a first visit without discarding technical guidance or adding a new site framework.

Baseline

The English README and Japanese README already present generated results and links to Pages, followed by extensive implementation-specific configuration, version and verification details. Current-state duplication has also produced the concrete guide inconsistencies tracked separately in #71.

Audit baseline, rechecked on 2026-09-18: 9b92c74cba34bd5a4bfc389075b9bef135131034. Refresh main when work begins.

Scope

  1. Organize both READMEs around purpose, verified results, interpretation/limitations, the shortest safe local quick start and links to deeper documentation.
  2. Move or consolidate detailed per-implementation setup, pinned-version explanations and acceptance procedures into appropriate public guides. Preserve technical information and avoid creating duplicate competing sources of truth.
  3. Keep registration, active cohort, published results and release snapshots visibly distinct. Use canonical links established by Align implementation guides with the current cohort and CI registry #71 rather than duplicating dynamic counts everywhere.
  4. Preserve generated result markers, exact measured values, source/run provenance, charts and links to the displayed publication/history. Do not replace existing results or hard-code a future cohort.
  5. Check English/Japanese parity, all moved links/anchors and executable commands. State prerequisites and destructive cleanup/reset behavior explicitly.

Acceptance criteria

  • Both languages provide the same essential story and working navigation to results, methodology and implementation guides.
  • A reader can find a minimal local example without installing every implementation's host toolchain unnecessarily.
  • Necessary runtime, safety, contract and verification instructions remain available in linked versioned guides.
  • Generated benchmark sections remain compatible with benchmark.generate_readme --check; no numeric result changes are introduced.
  • Relevant documentation, registry and site checks pass; published JSON/history/charts are unchanged.
  • No new frontend dependency, broad website redesign, runtime change or workflow redesign is required.

Dependencies and boundaries

Prefer completing #71 first so the cleanup builds on a consistent current-state explanation. This is a documentation-structure task, not a dependency of #70, #72 or Java diagnostics.

No official measurement, publication, cohort activation, release/tag change or settings mutation is included. #52 stays deferred; this task does not satisfy #59. Follow AGENTS.md: scratch investigations and Superpowers plans remain under ignored local-only directories, while durable public guides stay in Git.

Activity

  1. tappe9 commented on Sep 27, 2026

    @tappe9
    OwnerAuthor

    Dependency/status update — 2026-09-28

    The preferred prerequisite #71 is complete via merged PR #78 (c1d8e81b959e2c0ee0e5c4a1d8a7491790479f93). docs/IMPLEMENTATIONS.md now provides the shared registration/CI/cohort/publication boundaries, with links from Flask, Axum, Java and Express guides.

    Keep this issue open: #78 changed five guides and one regression test, not either README. The bilingual README information architecture, relocation of detailed setup, quick-start/command review and parity work in this issue have not been completed by that PR. Reuse the shared guide rather than duplicate status counts when this issue is implemented.

    The newly authorized official-measurement operation and producer-to-Pages verification belong to #59; refreshing generated result blocks would not by itself complete this README-restructuring issue. No implementation work for #74 was performed in this status update.

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

    enhancementNew or improved functionality

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions