lukehoban/browser

Improve README onboarding and contributor guidance

开放

#105 创建于 2026年6月13日

 (0 条评论) (0 个反应) (0 位负责人)Go (2 个派生)github user discovery
documentationgood first issue

仓库指标

星标
 (1 个星标)
PR 合并指标
 (30 天内没有已合并 PR)

描述

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.

贡献者指南