lukehoban/browser

Improve README onboarding and contributor guidance

Open

#105 opened on Jun 13, 2026

View on GitHub
 (0 comments) (0 reactions) (0 assignees)Go (1 fork)github user discovery
documentationgood first issue

Repository metrics

Stars
 (1 star)
PR merge metrics
 (PR metrics pending)

Description

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