Repository navigation
Description
Bring over TypeKit's plain-docs skill as .claude/skills/plain-docs, then rewrite the consumer-facing pages in its voice: plain, friendly, example-first and exact.
The pages are:
- the root
README.mdand the four package READMEs docs/getting-started.md,ranges.md,value-sets.md,serialization.md,efcore.md,migration.mdandwhy.md
A rewrite changes the voice, not the promises. Each page gets a claim-by-claim fact review against the code before it lands: every condition, exception and version note survives, and every new sentence matches the source. The OpenAPI transformer in docs/serialization.md stays verbatim with the test copy.
State on 2026-10-17: committed, not pushed, on docs/plain-docs-skill: the skill in 8159dbd, then the rewrite of all 12 pages in 68d9c6f (+2154 / −953). Every code block is unchanged byte for byte, and every heading that something links to is kept. The fact review corrected six claims that were already wrong before the rewrite. The commit message lists them:
- getting-started: any query over a server-computed
Unionother than the allowed operators throws, not only equality (since 9.0.0) - why:
decimal,DateTimeandDateTimeOffsetare continuous;doubleandfloatfail the total-order requirement - ranges: three factory methods and two properties, not four methods
- value-sets: the extra 7.0.0 wrapper requirement is the pinned format, temporal versions only
- EF Core NodaTime README:
Intersect/Except/Addfail in aWhereand run in memory in aSelect - EF Core README:
lower()/upper()are NULL on an unbounded side or an empty range
Lands after #37. claims.json quotes these pages verbatim, and OracleCatalogueTests fails on any quote the rewrite rewords. So the oracle machinery merges first. The rewrite then re-anchors each stale quote to the sentence that now carries the same promise, and the catalogue is the check that no promise was lost. A claim with no new sentence to anchor to means the rewrite dropped a promise: put it back, don't delete the claim.
Activity
[-]Adopt the plain-docs voice skill for consumer docs[/-][+]Adopt the plain-docs voice and rewrite the consumer docs in it[/+]