fix(DOC-1919): address review feedback on aws-iam-aurora guide#396
Conversation
📝 WalkthroughWalkthroughThe AWS IAM Aurora documentation page was restructured and updated to improve content organization and usability. Changes include adding page metadata (topic type, personas) and learning objectives, renaming instructional sections from numbered steps to outcome-focused titles (Find, Create, Grant, Configure), consolidating the "How it works" section, updating internal cross-references, standardizing placeholder names to lowercase across CLI examples and YAML snippets, and adding a "Next steps" section with links to related CDC input documentation. Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
✅ Deploy Preview for redpanda-connect ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
modules/guides/pages/cloud/aws-iam-aurora.adoc (1)
27-270: Consider explicit section IDs to make cross-references resilient.Current
<<Section Title>>refs work, but they’re fragile if headings are edited again. Adding explicit anchors would prevent future link drift.Suggested refactor
+[[find-pipeline-iam-role-name]] == Find the pipeline IAM role name ... -* An IAM role associated with the Redpanda Connect pod (see <<Find the pipeline IAM role name>>) +* An IAM role associated with the Redpanda Connect pod (see <<find-pipeline-iam-role-name>>)Apply similarly for the other repeatedly referenced sections.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/guides/pages/cloud/aws-iam-aurora.adoc` around lines 27 - 270, Add explicit AsciiDoc anchors for fragile section headings so cross-references use stable IDs; for each repeatedly referenced section (e.g., "Find the pipeline IAM role name", "Find the Aurora cluster resource ID", "Create the database connect role", and "Grant the pipeline role cross-account access") add an explicit ID line like "[[find-pipeline-role]]" immediately above the heading and update existing <<Find the pipeline IAM role name>>-style refs to use those IDs (e.g., <<find-pipeline-role>>) so links remain stable if headings change; apply the same pattern for all other referenced sections mentioned in the document.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@modules/guides/pages/cloud/aws-iam-aurora.adoc`:
- Around line 27-270: Add explicit AsciiDoc anchors for fragile section headings
so cross-references use stable IDs; for each repeatedly referenced section
(e.g., "Find the pipeline IAM role name", "Find the Aurora cluster resource ID",
"Create the database connect role", and "Grant the pipeline role cross-account
access") add an explicit ID line like "[[find-pipeline-role]]" immediately above
the heading and update existing <<Find the pipeline IAM role name>>-style refs
to use those IDs (e.g., <<find-pipeline-role>>) so links remain stable if
headings change; apply the same pattern for all other referenced sections
mentioned in the document.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 05538255-66ae-4ea2-a3d6-8a20bef33719
📒 Files selected for processing (1)
modules/guides/pages/cloud/aws-iam-aurora.adoc
- Remove step numbers from procedure headings; update internal xrefs - Add :page-topic-type:, :personas:, and :learning-objective-N: attributes - Standardize placeholders to <lowercase-dashes> throughout - Fold two-hop role chain into intro; remove standalone "How it works" section - Add context paragraph under Troubleshooting heading - Change troubleshooting subheading to code span - Add Next steps section - Style fixes: sentence fragments before code blocks, "once" -> "after", "this guide" -> "this page", redundant "IAM" in policy description, pipe-to-jq formatting in network config code block, passthrough for double-underscore topic name in inline code span Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Apply CodeRabbit's anchor-resilience suggestion: declare explicit [[anchor-id]] for the four H2 sections that have xref consumers, and convert each <<Section Title>> reference to <<id,Section Title>> so the links survive future heading rewrites. Sections anchored: - find-pipeline-iam-role-name - find-aurora-cluster-resource-id - create-database-connect-role - grant-pipeline-cross-account-access Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Feediver1
force-pushed
the
fix/doc-1919-kat-review
branch
from
5f7b179 to
469a4c5
Compare
Defensive coverage for future heading rewrites: every H2 and H3 now has an explicit [[anchor-id]] declaration. Currently only four anchors are xref'd elsewhere; the rest catch the case where a future contributor adds a reference to a section whose heading text later changes. Added anchors: - prerequisites - trust-policy - required-tag - create-the-role - configure-the-network - configure-the-pipeline - troubleshooting - err-sts-assumerole - next-steps Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Final standards pass. The AsciiDoc changes look great: sentence-case headings with explicit anchors, valid learning objectives/personas, xref targets resolve, no em dashes, and CodeRabbit's anchor suggestion is applied.
One thing to confirm before merge (cross-repo, likely a follow-up): this page carries tag::single-source[] markers, but unlike its siblings aws.adoc and gcp.adoc it has no stub in cloud-docs (modules/develop/pages/connect/guides/cloud/aws-iam-aurora.adoc with include::connect:guides:cloud/aws-iam-aurora.adoc[tag=single-source] plus a ROOT/nav.adoc entry). As a result the guide only publishes under the standalone Redpanda Connect docs, not under Redpanda Cloud, even though DOC-1919 targets Cloud customers and postgres_cdc/mysql_cdc are Cloud-supported. Is the Cloud stub intentionally deferred, or should we open a cloud-docs follow-up (plus a whats-new-cloud entry)? The fix can't live in this repo's PR, so flagging for a decision.
Optional nit (no change needed): the body says config applies to postgres_cdc, pg_stream, and mysql_cdc, but Next steps links only the first and last. That's fine, since pg_stream lives on the postgres_cdc page.
|
Companion cloud-docs PR opened for the missing Pattern B single-source stub: redpanda-data/cloud-docs#612. The two should land together so the Aurora IAM-roles guide publishes on both the standalone Connect docs and Redpanda Cloud surfaces. PR also includes a What's New (June 2026) entry on the cloud side. |
The Aurora IAM-roles authentication guide in rp-connect-docs#396 carries tag::single-source[] markers but had no cloud-docs stub, so the guide only publishes under the standalone Redpanda Connect docs. Since DOC-1919 targets Cloud customers and postgres_cdc/mysql_cdc are Cloud-supported, this stub completes the Pattern B single-source. - Stub at modules/develop/pages/connect/guides/cloud/aws-iam-aurora.adoc follows the same shape as sibling stubs aws.adoc and gcp.adoc - nav.adoc entry added under "Cloud Credentials", between aws and gcp - whats-new-cloud entry added under June 2026 Companion PR: redpanda-data/rp-connect-docs#396 Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
3 participants
Summary
Addresses review feedback from Kat on the aws-iam-aurora guide (merged in #388 before Kat could review).
:page-topic-type:,:personas:, and:learning-objective-N:attributes<lowercase-dashes>stylepostgres_cdcandmysql_cdcinputsonce→after, "this guide" → "this page", redundant "IAM", pipe-to-jq formatting, passthrough for__redpanda.connect.logsinline code spanPreview pages
Test plan
🤖 Generated with Claude Code