This issue tracks a comprehensive copy review to polish all user-facing text in PgQue for clarity, correct American English, consistency with the postgres-ai writing standards, and SEO/LLM friendliness. The goal is prose that reads as if written by a careful native technical writer for engineers, while preserving 100% of the technical meaning (no changes to code, SQL, commands, flags, identifiers, versions, or benchmark numbers).
Fixes will arrive as a pull request for review and are not merged automatically. Work is grouped into edit tasks below; files marked Fable get the highest-polish prose treatment, the rest get a technical copy edit.
Status: copy review complete. PR: #348. Every file below was reviewed against the style contract; files with prose defects were edited, and files already at native quality were reviewed and left as-is (noted per task).
Files to polish
Critical prose (Fable-level treatment)
Task readme (Fable):
Task landing (Fable) -- landing page; edit only human-readable text nodes and the prose in the feature/comparison content strings, never markup, classes, imports, or code:
Task docs-guides-1 (Fable):
Task docs-guides-2 (Fable):
Task clients (Fable) -- user-facing client-library READMEs:
Technical copy edit (Opus-level treatment)
Task docs-reference (Opus) -- function reference; leave signatures, parameter names, and code untouched:
Task meta (Opus) -- reviewed; already native-quality, no edits needed:
Task bench-1 (Opus) -- benchmark docs; never alter numbers, tables, or hardware/config values:
Task bench-2 (Opus) -- benchmark run READMEs; numbers/tables are data:
Task brief (Opus) -- published design brief; edit only human-readable HTML text nodes and metadata (title, meta description), never tags, styles, or structure:
Deliberately not modified
Internal working documents, generated output, legal text, and code whose strings are asserted by tests:
- blueprints/ (all: SPECx.md, PHASES.md, BENCH_XMIN_HORIZON.md, BETTER_DOCS.md, COOPERATIVE_CONSUMERS.md, idempotency/DESIGN.md, idempotency/SPEC.md, partition-keys/SPEC.md, partition-keys/decisions.md) -- internal design specs and working docs.
- CLAUDE.md -- AI agent engineering instructions, not user-facing.
- clients/go/RELEASE.md, clients/python/RELEASE.md, clients/ruby/RELEASE.md, clients/typescript/RELEASE.md -- internal release-process runbooks.
- web/public/briefs/partition-keys/index.html and v0.1.html through v0.8.html -- frozen, superseded version-history snapshots of the design brief (internal draft iterations); only the live brief is polished.
- benchmark/xmin-horizon/results/results.md -- generated benchmark results; the tables are load-bearing data.
- NOTICE, LICENSE -- legal attribution and license text.
- web/src/components/docs/SocialIcons.astro, web/src/components/docs/ThemeSelect.astro -- UI widget markup with standard icon/theme labels.
- web/src/styles/custom.css -- pure CSS, no prose.
- sql/ and devel/sql/ SQL sources, tests/ -- SQL RAISE messages and client sentinel error strings (e.g. clients/go/errors.go) are asserted verbatim by the test suite; see the note below.
SEO and LLM friendliness ideas
The landing page (web/src/pages/index.astro) and every docs/*.md page already carry good metadata: a keyword-bearing <title> / frontmatter title, a self-contained <meta name="description"> / frontmatter description, a canonical URL, and OG/Twitter tags. The H1 ("Zero-bloat Postgres queue.") already leads with the primary search term. So the copy pass focused on tightening first paragraphs into self-contained, quotable summaries (done in this PR for docs/README.md, docs/tutorial.md, docs/examples.md, and clients/README.md). Concrete ideas for a follow-up, none of which touch code or invent claims:
Landing page (web/src/pages/index.astro)
- Add JSON-LD structured data (
<script type="application/ld+json">) describing a SoftwareApplication (or SoftwareSourceCode) with name: "PgQue", applicationCategory: "DeveloperApplication", operatingSystem, license (Apache-2.0), and sameAs pointing to the GitHub repo. Lets Google and LLMs recognize PgQue as a named software product. This is additive markup, so it was deferred out of the prose-only PR.
- Add a
FAQPage JSON-LD block built from questions the page already answers ("Does it work on RDS / Aurora / Supabase / Neon?", "Does it need a C extension or a daemon?", "How is it different from a SKIP LOCKED job queue?"). High-value for LLM answer extraction and Google rich results.
- Add
<meta name="twitter:title"> and <meta name="twitter:description"> (only twitter:card is present) so the Twitter/X card text is explicit rather than falling back to OG.
- Add
<meta property="og:image:alt"> describing the OG image for accessibility and card previews.
Docs pages
- Emit
TechArticle or Article JSON-LD per docs page from the existing frontmatter title + description (Starlight can inject this via a head config), reinforcing each page as a distinct indexable document.
- Add
BreadcrumbList JSON-LD (Home -> Docs -> page) to strengthen the site hierarchy in search results.
- Tighten a few H2s toward searched phrasing where it stays natural, e.g. framing tutorial/monitoring headings around "Postgres queue" and "dead-letter queue" so section anchors carry the query terms.
Repo / README
- Add an
llms.txt at the site root (and a repo copy) listing the canonical docs URLs with one-line descriptions (tutorial, reference, examples, concepts, monitoring, latency-and-tuning), so LLM crawlers get a curated, low-noise map of the documentation.
- Keep the README's one-logical-H1 structure and the "Contents" table of contents; both already help LLM chunking and internal linking. Consider ensuring every docs page cross-links back to the tutorial and reference (most already do) to strengthen internal linking.
- Canonical naming is already consistent:
pgque for schema/package/CLI/identifiers, PgQue for prose/headings, PgQ for the upstream engine. Worth keeping this exact convention in any new marketing or blog copy so search and LLMs disambiguate the three.
Brief page (web/public/briefs/partition-keys.html)
- The
<title> uses a middot breadcrumb form ("PgQue Brief · Partition Keys · v0.8"); it already has a strong <meta name="description">. If these briefs are meant to rank, add <link rel="canonical"> and an OG title/description mirroring the meta description.
Follow-ups (not part of this pass)
- Source-code user-facing strings (SQL
raise exception/notice text under devel/sql/, and Go/Python/Ruby/TypeScript client error strings) were reviewed but deliberately left out of the edit tasks: many are matched verbatim by the test suite (e.g. tests/test_*.sql, clients/go/errors_test.go), so touching them risks breaking tests and would require regenerating sql/pgque.sql via build/transform.sh. If desired, a separate, test-aware pass could clean up wording where no test asserts the string.
- Structured-data (JSON-LD),
llms.txt, and the extra social/OG meta tags listed above are additive markup/files, not prose, so they were deferred from this prose-only PR to a dedicated SEO follow-up.
This issue tracks a comprehensive copy review to polish all user-facing text in PgQue for clarity, correct American English, consistency with the postgres-ai writing standards, and SEO/LLM friendliness. The goal is prose that reads as if written by a careful native technical writer for engineers, while preserving 100% of the technical meaning (no changes to code, SQL, commands, flags, identifiers, versions, or benchmark numbers).
Fixes will arrive as a pull request for review and are not merged automatically. Work is grouped into edit tasks below; files marked Fable get the highest-polish prose treatment, the rest get a technical copy edit.
Status: copy review complete. PR: #348. Every file below was reviewed against the style contract; files with prose defects were edited, and files already at native quality were reviewed and left as-is (noted per task).
Files to polish
Critical prose (Fable-level treatment)
Task
readme(Fable):Task
landing(Fable) -- landing page; edit only human-readable text nodes and the prose in the feature/comparison content strings, never markup, classes, imports, or code:Task
docs-guides-1(Fable):Task
docs-guides-2(Fable):Task
clients(Fable) -- user-facing client-library READMEs:Technical copy edit (Opus-level treatment)
Task
docs-reference(Opus) -- function reference; leave signatures, parameter names, and code untouched:Task
meta(Opus) -- reviewed; already native-quality, no edits needed:Task
bench-1(Opus) -- benchmark docs; never alter numbers, tables, or hardware/config values:Task
bench-2(Opus) -- benchmark run READMEs; numbers/tables are data:Task
brief(Opus) -- published design brief; edit only human-readable HTML text nodes and metadata (title, meta description), never tags, styles, or structure:Deliberately not modified
Internal working documents, generated output, legal text, and code whose strings are asserted by tests:
SEO and LLM friendliness ideas
The landing page (
web/src/pages/index.astro) and everydocs/*.mdpage already carry good metadata: a keyword-bearing<title>/ frontmattertitle, a self-contained<meta name="description">/ frontmatterdescription, a canonical URL, and OG/Twitter tags. The H1 ("Zero-bloat Postgres queue.") already leads with the primary search term. So the copy pass focused on tightening first paragraphs into self-contained, quotable summaries (done in this PR for docs/README.md, docs/tutorial.md, docs/examples.md, and clients/README.md). Concrete ideas for a follow-up, none of which touch code or invent claims:Landing page (
web/src/pages/index.astro)<script type="application/ld+json">) describing aSoftwareApplication(orSoftwareSourceCode) withname: "PgQue",applicationCategory: "DeveloperApplication",operatingSystem, license (Apache-2.0), andsameAspointing to the GitHub repo. Lets Google and LLMs recognize PgQue as a named software product. This is additive markup, so it was deferred out of the prose-only PR.FAQPageJSON-LD block built from questions the page already answers ("Does it work on RDS / Aurora / Supabase / Neon?", "Does it need a C extension or a daemon?", "How is it different from a SKIP LOCKED job queue?"). High-value for LLM answer extraction and Google rich results.<meta name="twitter:title">and<meta name="twitter:description">(onlytwitter:cardis present) so the Twitter/X card text is explicit rather than falling back to OG.<meta property="og:image:alt">describing the OG image for accessibility and card previews.Docs pages
TechArticleorArticleJSON-LD per docs page from the existing frontmattertitle+description(Starlight can inject this via a head config), reinforcing each page as a distinct indexable document.BreadcrumbListJSON-LD (Home -> Docs -> page) to strengthen the site hierarchy in search results.Repo / README
llms.txtat the site root (and a repo copy) listing the canonical docs URLs with one-line descriptions (tutorial, reference, examples, concepts, monitoring, latency-and-tuning), so LLM crawlers get a curated, low-noise map of the documentation.pgquefor schema/package/CLI/identifiers,PgQuefor prose/headings,PgQfor the upstream engine. Worth keeping this exact convention in any new marketing or blog copy so search and LLMs disambiguate the three.Brief page (
web/public/briefs/partition-keys.html)<title>uses a middot breadcrumb form ("PgQue Brief · Partition Keys · v0.8"); it already has a strong<meta name="description">. If these briefs are meant to rank, add<link rel="canonical">and an OG title/description mirroring the meta description.Follow-ups (not part of this pass)
raise exception/noticetext under devel/sql/, and Go/Python/Ruby/TypeScript client error strings) were reviewed but deliberately left out of the edit tasks: many are matched verbatim by the test suite (e.g. tests/test_*.sql, clients/go/errors_test.go), so touching them risks breaking tests and would require regenerating sql/pgque.sql via build/transform.sh. If desired, a separate, test-aware pass could clean up wording where no test asserts the string.llms.txt, and the extra social/OG meta tags listed above are additive markup/files, not prose, so they were deferred from this prose-only PR to a dedicated SEO follow-up.