pgjdbc/pgjdbc GitHub issues and pull requests (mirror)
help / color / mirror / Atom feedFrom: vlsi (@vlsi) <[email protected]>
To: pgjdbc/pgjdbc <[email protected]>
Subject: Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases
Date: Fri, 22 May 2026 09:54:33 +0000
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
## Editorial pass per docs/CLAUDE.md
37 files under `docs/content/`, all outside `changelogs/`. The pass is mechanical for the most part, with targeted fixes for the grammar mistakes that turned up along the way (subjunctive, possessive, subject-verb, missing articles, duplicated tokens).
The diff is balanced: 361 insertions vs 362 deletions, no new paragraphs, no restructuring.
The pass was run by ten parallel sub-agents, one per content subtree (top-level, documentation root, getting-started, connect, query, data-types, security, postgresql-features, runtime + reference, troubleshooting). Each agent received the full style guide inline and a rule against inventing edits to justify the run.
The reading approach that worked locally: **IntelliJ side-by-side diff with soft wrap on and "Ignore whitespace" on**. Most changes are punctuation swaps that shift surrounding word wraps; ignoring whitespace makes the real edits jump out.
### What changed
Commit: https://github.com/pgjdbc/pgjdbc/pull/4075/commits/2b6fc513c468cba24c6045c62588d9d1e3b3524e
- **Em-dash** is the single largest category. Section headings, `**Term** — definition` bullets, paragraph-level connectors, and paired parentheticals were all converted to `:`, `.`, `;`, commas, or parentheses. The rendered HTML stays close to identical for most of these; the change is in the reading flow, not the visible layout.
- **American English** normalized across pages where British forms had drifted in: `behaviour`, `organise`, `recognise`, `synchronise`, `artefact`, `backwards`, and so on.
- **Inclusive wording** applied to prose: `master switch` → `top-level switch` (one heading in `prepared-statements.md`); `Master/Secondary` → `primary/standby` in `replication.md`. Literal config values, API names, and external identifiers were left as-is.
- **Grammar mistakes** picked up along the way: `who's column names` → `whose column names`, `It's looks` → `It looks`, `WAL's that that` → `WALs that`, `your must` → `you must`, an unclosed parenthesis in `binary-bytea.md`, and a broken inline-code identifier (`propertypreferQueryMode=simple` → property `preferQueryMode=simple`) in `security/_index.md`.
### How to review
Suggested order, biggest diffs first:
1. `postgresql-features/replication.md`: ~54 changes. The largest single file. Grammar density was high (duplicated tokens, missing articles, missing periods). Also the only file where `Master/Secondary` → `primary/standby` affects the rendered prose.
2. `query/prepared-statements.md`: ~35 changes. Includes the `master switch` → `top-level switch` heading rename. Definition lists converted from `—` to `:` throughout.
3. `security/authentication.md`: ~29 changes. Front-matter description plus many definition-list bullets.
4. `query/batch-inserts.md`: ~24 changes. The "This page is the explanation that backs..." paragraph was rewritten per the "don't define the page topic in its own body" rule.
5. The nine `troubleshooting/` pages, ~50 edits total: mostly mechanical. `—` in Related lists became `:`; `artefact` became `artifact`; a few paired-parenthetical rewrites.
Everything else is single-digit edits and reads fast.
### What was not touched
- `docs/content/changelogs/*.md` (release-note imports; excluded by pre-agreement).
- `docs/archetypes/default.md` (Hugo template, outside `docs/content/`).
view thread (64+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: github://pgjdbc/pgjdbc
Cc: [email protected], [email protected]
Subject: Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases
In-Reply-To: <<[email protected]>>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox