Skip to content

handbook: rewrite introduction page to actually introduce Beacon #101

@nerdalytics

Description

@nerdalytics

The introduction page currently serves two purposes and does neither well. The top half introduces Beacon (API listing, what signals are, how dependency tracking works). The bottom half is a changelog for the current version ("Changes from v1000.3.1", migration link).

A reader landing on the introduction page wants to understand what Beacon is, when to use it, and how to think about it. They do not want a diff against the previous release. That belongs in the migration guide, which already exists.

What the introduction should cover

  • What Beacon is in one sentence
  • The mental model: signals, effects, and the dependency graph
  • A small working example that shows the reactive loop in action
  • When Beacon is the right choice (and when it isn't)
  • How to read the rest of the handbook

What should move out

  • The "Changes from" section duplicates content from the migration page. Remove it from the introduction and link to migration for readers who want the version diff.
  • The constraints section (line count, zero dependencies) is factual but reads as a spec sheet. Weave the relevant parts into the introduction naturally.

Per-version consideration

Every version directory has its own introduction page. The shared content (what Beacon is, mental model, example) is identical across versions. Only the "Changes from" section differs, and that section is the one being removed. After this rewrite, the introduction pages should be nearly identical across versions, varying only where the API surface genuinely changed (e.g., v1.0.0 used derived() instead of derive()).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions