docs: sentence-level polish across README + docs/#65
Merged
Conversation
Follow-up from DevRel round 3. No structural changes; tightens
wording across every user-facing doc. Grouped by file:
README
- Framing paragraph: "in a form that fits modern Postgres" -> "in a
form that runs on any Postgres platform, managed providers
included." The old wording misread as "Postgres can run PgQue" —
Postgres can run old PgQ too; the actual contrast is platform
availability (managed providers block C extensions).
- §Project status: drop "rock solid" flourish; "battle-tested at
Skype scale for over a decade" carries the weight.
- §Client libraries: drop throat-clear "On top of that", cut "very
much appreciated" pad -> "Contributions welcome."
docs/README.md
- Index lead: drop the countable "Five short docs" (dates itself);
"Short docs for users, plus a contributor primer."
- Promote pgq-concepts entry phrasing: "ticker contract" ->
"ticker rule" so it matches the glossary section name.
docs/tutorial.md
- Opening: drop "This is" throat-clear; tighten "willing to install
into" -> "to install into"; tighten "the whole thing" -> "the
system"; flip "illustrative ids" disclaimer to active voice.
- Step 2: drop "actually" from create_queue return-code sentence.
- Step 3: tighten echo after code block; drop "A brief callout on
overloads:" throat-clear.
- Step 4: drop "it is worth being explicit about why" -> "Here is
why."; drop "individual rows" ("rows" alone is fine).
- Step 5: "event-count threshold" -> "tick thresholds" (aligns with
reference), drop "actually produce" -> "produce".
- Step 6: drop "Note" throat-clear.
- Step 7: "Real consumers" -> "Consumers".
- Step 7: "does exactly that" pad -> "." (sentence end), merge with
next sentence.
- Step 7: "That is the redelivery." merged into the prior line.
- Step 8: "That is two more nack cycles." -> "Two more nack cycles."
(avoids duplicate "That is" opener).
- Step 8: "instead of to the retry queue" -> "instead of the retry
queue"; "After it runs, no events come back out of receive" ->
"After the second iteration, receive returns nothing".
- Step 8: "Two useful moves from here." -> "From here, two moves."
- Step 9: "Three functions give you a quick read" -> "Three
functions read out queue and consumer health" (align with
examples.md Monitoring noun phrasing).
- Production cadence: correct the "three cron jobs" claim to "four
cron jobs" (retry_events is scheduled since PR #63 merged); update
pg_cron log hygiene volume from 2,000 rows/hour (2-second cadence)
to 3,600 rows/hour (1-second cadence).
- Next steps: drop "and why it is worth trusting" on history link —
asks the reader to trust, simpler just "how this engine came from
PgQ."
docs/reference.md
- Intro: tighten "This reference documents the complete function
surface shipped by" -> "Every function shipped in"; drop "worth
knowing" from form template; "call shape is not obvious from the
signature alone" -> "signature alone leaves the call ambiguous".
- Intro: "This document is the lookup table you reach for
afterwards." -> "Use this as the lookup table."
- §Publishing (text overload): "the payload bytes are stored
verbatim" -> active voice "stores the payload bytes verbatim".
- §Consuming (nack): Otherwise-fragment joined with semicolon.
docs/examples.md
- Intro: "A few common" -> "Common".
- §Batch send: "ship — see the reference for when to pick which"
-> "exist — the reference explains the trade-off."
- §Fan-out: `skip locked` backticks removed; now reads "SKIP LOCKED"
(matches README voice). Drop redundant "Produce, tick, and then
receive:" line (the code block below already says this).
- §Fan-out closer: clarify "its own consumer" antecedent ->
"Each consumer sees the same event through its own cursor".
- §Exactly-once: de-tautologize "rolls back ... rolls back ... roll
back together" -> "either all commit or none do".
- §Exactly-once: trim "reads the same" -> "is equivalent".
- §DLQ: "from there" -> "." (new sentence).
- §Monitoring: "one-shot read of the system" -> "read out queue
and consumer health" (align with tutorial Step 9).
- §Monitoring: break the em-dash-then-comma-then-and wall sentence
into two sentences.
docs/benchmarks.md
- Methodology line: drop "per-session" redundant parenthetical
(disclosed two sentences later).
- Key takeaways: "30-minute sustained test showed zero dead-tuple
growth" -> "a 30-minute sustained test: zero dead-tuple growth"
(drop redundant "showed" after "under load" bullet head).
- Closing line: "are ... are" echo fixed; "will be posted as they
become available" -> "Server-class numbers to follow."
docs/pgq-concepts.md
- Event row: "producer/consumer contract" -> "a producer/consumer
contract" (grammar); "; PgQue does not interpret it" ->
" — PgQue does not interpret it" (em dash for the aside).
docs/pgq-history.md
- Lineage: "PgQue inherits that engine; it does not reinvent it."
-> "PgQue inherits that engine rather than reinventing it."
(single clause, tighter).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up from the DevRel round 3 review. Sentence-level polish across every user-facing doc. No structural or content-shape changes — just tightening prose. Applies ~30 line-level nits that were deferred from the main docs PR (#59).
Highlights
pgque_retry_eventsjoined the set). Also updated pg_cron log-hygiene volume from 2,000 rows/hour (2-second cadence) to 3,600 rows/hour (1-second cadence, since PR fix: tick every 1 second to match pgqd cadence #64).Every change is line-level and boring by design. Commit message has the full per-file breakdown.
Test plan
🤖 Generated with Claude Code