Skip to content

Rewrite the consumer docs in the plain-docs voice #164

Closed

Description

@CaffeinatedCoder

Rewrite every consumer page in the plain-docs voice (#163), in one change: plain, friendly, example-first and exact.

The pages:

  • the root README.md
  • src/EFCore.ComplexIndexes/README.md, src/EFCore.ComplexIndexes.PostgreSQL/README.md, src/EFCore.ComplexIndexes.SqlServer/README.md (the NuGet landing pages)
  • docs/postgresql-indexes.md, docs/postgresql-constraints.md, docs/sqlserver.md, docs/upgrading.md

A rewrite changes the voice, not the promises. Each page gets a claim-by-claim review against the code before it lands: every condition, exception, SQLSTATE, provider limit and version note survives, and every new sentence matches the source. A statement found wrong on the way is corrected and listed in the PR.

  • Every code block stays byte for byte the same.
  • Every heading something links to keeps its anchor: the changelogs and published release notes link blob/main/…#anchor, and DocumentationLinkTests checks them. Other headings may become tasks, with every link updated.
  • Packed READMEs keep absolute links only.
  • The Documentation table in the root README matches the pages' new openings.

Lands after the open 5.5.0 doc changes. #149, #159 and #162 edit docs/upgrading.md, and #159 edits docs/postgresql-constraints.md. Whichever merges second rebases; the rewrite carries their sentences over in the new voice.

Done when the eight pages are rewritten, the unit suite passes, and a script shows every fenced block unchanged against main.

Activity

  1. added this to the 5.5.0 milestone on Oct 20, 2026
  2. CaffeinatedCoder commented on Oct 20, 2026

    @CaffeinatedCoder
    OwnerAuthor

    State on 2026-10-20: PR #166 rewrites all eight pages on top of main after #149 (+797 / −572). Every fenced block is unchanged and all 37 linked headings keep their anchors. Unit suite 605/605. Three claim-by-claim reviews found eight statements that were already wrong before this change. The PR fixes them and lists each one. #159 and #162 still edit docs/upgrading.md and docs/postgresql-constraints.md; whichever lands second rebases.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationpackage/coreAffects EFCore.ComplexIndexespackage/postgresqlAffects EFCore.ComplexIndexes.PostgreSQLpackage/sqlserverAffects EFCore.ComplexIndexes.SqlServer

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions