Skip to content

Adopt the plain-docs voice skill for the consumer docs #163

Closed

Description

@CaffeinatedCoder

Bring over the plain-docs skill from CodoMetis.ValueRanges and CodoMetis.TypeKit as .claude/skills/plain-docs, adapted to this repository. It sets the voice for every page a consumer reads: plain, friendly, example-first and exact.

What the adaptation changes from the ValueRanges copy:

  • Which pages. The root README.md, the three package READMEs under src/*/README.md, and docs/postgresql-indexes.md, docs/postgresql-constraints.md, docs/sqlserver.md and docs/upgrading.md. CONTRIBUTING.md, AGENTS.md, CLAUDE.md, ROADMAP.md, SECURITY.md and the changelogs keep their own style.
  • Plain words. The table uses this library's jargon: satellite, refuse/refusal, the differ, descriptor, scaffold, seam, wiring, sentinel, whitelist, consumer.
  • What must not change. The guards that exist here: DocumentationLinkTests (relative and absolute blob/main links and anchors resolve, packed READMEs link absolutely), DocumentationApiTests (every method a page names exists, and a provider page names no other provider's exclusive API), ChangelogConsistencyTests (no README carries a changelog copy, and the changelogs' Upgrading links), plus what nothing guards: code blocks are not compiled, and the headings that published changelogs and release notes link to.

The rewrite of the pages themselves is a separate issue.

Done when the skill is on main, CLAUDE.md lists it under Skills, and the unit suite passes.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions