Style sweep: em dashes, xref hygiene, prohibited words#18
Merged
Conversation
- Remove ~130 em dashes across 19 files. Convert `* *Term* — definition` description lists to `* *Term*: Definition` (with definitions capitalized); rewrite parenthetical em-dash pairs as parentheses, commas, or shorter sentences. Three all-fragment description lists lose closing periods to match the list-parallelism rule. - Replace relative `xref:../foo.adoc` paths in `mcp/pages/managed/` with fully qualified `xref:mcp:foo.adoc[]` (8 files). - Add missing module prefixes to bare `xref:foo.adoc[]` shortcuts across agents, ai-gateway, mcp, observability, and ROOT modules. - Replace `=== Step N: …` headings in `eject-to-custom-mode.adoc` (and the duplicated ROOT/partials copy) with descriptive headings. - Replace prohibited words: `via` → `through`, `e.g.` → `for example`, `etc.` → `and so on` (or removed where redundant). - Three passive-voice rewrites in configure-provider, create-server, and setup-guide. Other "is X-ed" cases left as-is since they describe state, not awkward agentive passive. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for redpanda-agentic-data-plane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- jira.adoc: "sprints, etc. (read-only operation)" → "sprints, and so on (read-only operation)". My earlier `etc.\)` regex missed the form with a space between `etc.` and `(`. - cost-tracking.adoc: "The master plan calls for…" → "The parent plan calls for…" in a TODO comment. Style guide bans "master" as a generic descriptor. Final state: zero adp-docs-sourced build errors, zero matches for em dashes, `Step N:` headings, relative xrefs, missing-module xref shortcuts, `please`/`via`/`etc.`/`e.g.`/`i.e.`, or deprecated terms. 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
Repo-wide style cleanup against
docs-team-standards. 73 files touched, 446 ins / 449 del. Six sweeps bundled into one PR (all mechanical or low-risk).* *Term* — definitiondescription lists become* *Term*: Definitionwith capitalized definitions; parenthetical em-dash pairs become parentheses, commas, or shorter sentences; three no-space em dashes get sentence-appropriate punctuation. Three all-fragment lists lose closing periods to satisfy the list-parallelism rule.xref:../foo.adocpaths inmcp/pages/managed/(8 files): rewritten to fully qualifiedxref:mcp:foo.adoc[].xref:agents:foo.adoc,xref:ai-gateway:foo.adoc, …).=== Step N: …headings inai-hub/eject-to-custom-mode.adoc(and its duplicated ROOT/partials copy): rewritten as descriptive headings.via→through,e.g.→for example,etc.→and so on(or removed when redundant).configure-provider.adoc,create-server.adoc,admin/setup-guide.adoc. Other "is X-ed" patterns left as-is since they describe state, not awkward agentive passive.Deferred (separate sweep): broader passive-voice rewrites in integrations and
ROOT/partials/migration-guide.adoc; cross-repo xref localization (tracked in memory).Preview pages
Test plan
npm run buildcompletes with zero adp-docs-sourced errors. Remaining warnings are pre-existing (unlisted pages, placeholder-attribute lookups in code blocks)./redpanda-adp/observability/transcripts/— description lists renderTerm: Definitionwith each definition starting with a capital letter./redpanda-adp/governance/guardrails/overview/— learning objective 2 reads "evaluator types (PII, Toxicity, and Custom webhook) and the situations each fits", not em dashes./redpanda-adp/ai-gateway/admin/setup-guide/— "Providers default to disabled; an administrator must explicitly enable each one." renders cleanly./redpanda-adp/mcp/managed/kafka/— sibling xrefs (User-delegated OAuth, etc.) resolve.grep -rn '—' modules/in adp-docs returns no hits.🤖 Generated with Claude Code