Skip to content

Adopt the plain-docs voice and rewrite the consumer docs in it #38

Closed

Description

@CaffeinatedCoder

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.md and the four package READMEs
  • docs/getting-started.md, ranges.md, value-sets.md, serialization.md, efcore.md, migration.md and why.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 Union other than the allowed operators throws, not only equality (since 9.0.0)
  • why: decimal, DateTime and DateTimeOffset are continuous; double and float fail 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/Add fail in a Where and run in memory in a Select
  • 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

  1. added this to the 9.1.0 milestone on Oct 17, 2026
  2. changed the title [-]Adopt the plain-docs voice skill for consumer docs[/-] [+]Adopt the plain-docs voice and rewrite the consumer docs in it[/+] on Oct 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

documentationImprovements or additions to documentation

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions