Skip to content

docs: use plainer prose in README and guides - #31

Merged
cardmagic merged 1 commit into
mainfrom
docs/plainer-prose
Aug 28, 2026
Merged

docs: use plainer prose in README and guides#31
cardmagic merged 1 commit into
mainfrom
docs/plainer-prose

Conversation

@cardmagic

Copy link
Copy Markdown
Owner

Prose-only pass over the README and docs/. No source, type, test, or
fixture file is touched.

Pattern Before → After
Cleft "X is what Y" "The combination is what costs" → "These three must agree with each other"
"X, not Y" closer "The argument for an actor is scope, not discipline" → "An actor helps when the work goes outside the scope of a lock"
Concessive flourish "That is less code than this library and it works" → "That needs less code than this library, and it is sufficient for that case"
Cliché "The database is the source of truth" → "The database holds the authoritative state"
Marketing aside "more than a counter-shaped happy path" → "more than a simple counter"
Metaphor "Two companions complete the local-first story" → "Two more modules support local-first applications"
Imperative chant "Choose celld to ... Choose Solid Objects to ..." → one comparative sentence

Also removed the last em dash in CHANGELOG.md and reworded the parity
ledger's "the wire contract is what both sides guarantee".

Validation

  • node scripts/check-documentation.mjs — exit 0
  • node scripts/check-parameter-style.mjs — exit 0
  • prettier --check README.md CHANGELOG.md docs/*.md — clean

Kept intact: the delivery-boundaries list, the parity statuses, every
benchmark figure, and the Shuffle Up and Play evidence table.

Remove the constructions that read as machine-written: the cleft
"X is what Y" sentences, the "X, not Y" closers, the concessive
"that is less code and it works", the "counter-shaped happy path"
aside, the "local-first story" metaphor, and the "Choose celld to /
Choose Solid Objects to" imperative pair.

Every technical claim, guarantee, benchmark number, and code sample is
unchanged. Prose only.
@greptile-apps

greptile-apps Bot commented Aug 28, 2026

Copy link
Copy Markdown

Greptile Summary

This PR rewrites README, changelog, API, authorization, benchmark, correctness, and parity documentation in plainer language without changing documented behavior.

  • Simplifies prose and removes metaphors, clichés, and marketing language.
  • Preserves API contracts, correctness boundaries, benchmark figures, compatibility claims, links, tables, and code examples.

Confidence Score: 5/5

The documentation-only changes appear safe to merge.

The revised prose preserves the documented runtime contracts, security boundaries, compatibility requirements, benchmark data, Markdown structure, and references, with no actionable defect identified.

Important Files Changed

Filename Overview
README.md Rewords product guidance and runtime explanations while preserving the documented guarantees and limitations.
CHANGELOG.md Replaces an em dash with sentence punctuation without changing the release note.
docs/api.md Clarifies that TypeScript declarations define exact signatures without altering API guidance.
docs/authorization.md Simplifies authorization prose while retaining the deny-by-default security boundary.
docs/benchmarks.md Rephrases benchmark limitations without changing figures or methodology.
docs/correctness.md Simplifies delivery and wake-up descriptions while preserving at-least-once and authoritative-state guarantees.
docs/parity.md Rewords parity and wire-contract explanations without changing compatibility statuses or payload requirements.

Reviews (1): Last reviewed commit: "docs: use plainer prose in README and gu..." | Re-trigger Greptile

@cardmagic
cardmagic merged commit ac45c7b into main Aug 28, 2026
19 checks passed
@cardmagic
cardmagic deleted the docs/plainer-prose branch August 28, 2026 03:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant