lukehoban/browser

Improve README onboarding and contributor guidance

Offen

#105 geöffnet am 13.06.2026

 (0 Kommentare) (0 Reaktionen) (0 zugewiesene Personen)Go (2 Forks)github user discovery
documentationgood first issue

Repository-Metriken

Stars
 (1 Stern)
PR-Merge-Metriken
 (Keine gemergten PRs in 30 T)

Beschreibung

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.

Contributor Guide