Skip to content

docs: align use-case claims and plainify prose - #56

Merged
cardmagic merged 1 commit into
mainfrom
docs/align-use-case-claims
Aug 28, 2026
Merged

docs: align use-case claims and plainify prose#56
cardmagic merged 1 commit into
mainfrom
docs/align-use-case-claims

Conversation

@cardmagic

Copy link
Copy Markdown
Owner

Two documentation commits, no code changes.

  1. docs: align use-case claims with the JS port — brings the Ruby
    use-case wording in line with the JS port, matching
    docs: align use-case claims with the Ruby gem solid-objects-js#30.
  2. docs: use plainer prose in README and guides — removes the
    rhetorical constructions that read as machine-written.

What the prose pass changed

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 gem and it works" → "That needs less code than this gem, and it is sufficient for that case"
Personification "The lock ... has no say over which push arrives last" → "The lock sets the write order, but it does not set the order in which the pushes arrive"
Aphorism "Sequential does not mean once" → "Ordered execution does not prevent repeated execution"

Validation

Markdown only. No Ruby source, signature, migration, or test file is
touched, so rake behavior is unchanged. Every guarantee, benchmark
number, policy name, and code sample is preserved verbatim.

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 anthropomorphic "that example
wants three things", and aphorisms such as "Sequential does not mean
once".

Every technical claim, guarantee, benchmark number, policy name, and
code sample is unchanged. Prose only.
@cardmagic
cardmagic merged commit 74a5388 into main Aug 28, 2026
40 checks passed
@cardmagic
cardmagic deleted the docs/align-use-case-claims 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