Skip to content

docs(get-started): rewrite the introduction in Simplified Technical English (#120) #122

Description

@maehr

Context

Deferred from #120, which is closed. #121 fixed the eight other acceptance criteria of that
review and landed on staging as 56cab1b. This one remains, and it is not a false published
claim, so it does not block the v0.1.0 tag.

The finding, as #120 stated it

src/content/docs/get-started/index.md:10-20 uses long sentences, fragments, metaphors ("the
citation becomes the doorway"), and ambiguous claims such as "No central host."

The page is the front door of the site. A reader who does not read English as a first language
meets it first, and a translator meets it next. The prose is written for effect rather than for
transfer.

The unconditional persistence claim in the same paragraph is already fixed in 56cab1b: the
sentence now reads "permanent once the record is active". Only the style question is open.

What to do

  1. Replace the opening with short, literal statements. review: address PR #4 clarity and minimalism findings before v0.1.0 #120 proposed this shape:

    TextRefs assigns a URI to a passage. It does not host text or replace editions. It links the
    passage to editions, identifiers, and resolver URLs. Only active records have a persistence
    guarantee.

  2. Define the four record types in a table or a short list.

  3. Keep every fact the current page states. This is a rewrite for style, not a cut of scope.

  4. Apply the same pass to the de translation of the page, so the pair does not drift.

Acceptance criteria

  • The get-started introduction uses short, literal, status-accurate sentences.
  • Each instruction sentence is under 20 words, and each descriptive sentence is under 25.
  • The four record types appear as a table or a short list.
  • No metaphor stands in for a technical statement.
  • npm run verify passes.

Related: #4, #120, #121.

Activity

  1. added
    documentationImprovements or additions to documentation
    post-v0.1.0Deferred past the v0.1.0 baseline. Revisit if the need arises.
    on Sep 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationpost-v0.1.0Deferred past the v0.1.0 baseline. Revisit if the need arises.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions