lukehoban/browser

Improve README onboarding and contributor guidance

Aperta

#105 aperta il 13 giu 2026

 (0 commenti) (0 reazioni) (0 assegnatari)Go (2 fork)github user discovery
documentationgood first issue

Metriche repository

Star
 (1 stella)
Metriche merge PR
 (Nessuna PR mergiata in 30 g)

Descrizione

Summary

The root README.md already has good high-level content, but it could do a better job of onboarding both users and contributors. Important information is present, but some of it is scattered, duplicated, or missing from the first-read experience.

Problems observed

  • The README does not state prerequisites up front (for example, the repository currently targets Go 1.24.11 in go.mod).
  • The project’s scope and limitations are implied, but not summarized early for readers who may expect a full interactive browser.
  • The "Quick Start", testing, and WebAssembly instructions are spread across multiple sections/documents without a concise task-oriented flow.
  • The testing command appears under the screenshots section, which makes the document harder to scan.
  • Contributor-specific expectations (for example where to find milestones/testing docs and when screenshots should be refreshed for rendering changes) are not surfaced clearly in the main README.

Suggested improvements

  • Add a short prerequisites section near the top.
  • Add a brief "What this project is / is not" summary.
  • Reorganize quick-start content into clearer tasks:
    • build the CLI
    • render a local file
    • render a remote URL
    • run tests
    • run the WASM demo
  • Move testing instructions into their own section.
  • Add a short contributor section linking to MILESTONES.md, TESTING.md, and screenshot expectations.
  • Review the README for duplicated or overly long sections and tighten the flow.

Acceptance criteria

  • A new reader can understand the project scope within the first screenful of the README.
  • A contributor can find the main build/test/demo commands quickly.
  • The README clearly points to deeper docs without forcing readers to hunt through the repo.
  • Testing and contributor guidance are in logically named sections.

Guida contributor