DOC-1487 apply coderabbit cloud-docs suggestions #348
Conversation
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis pull request introduces a series of small documentation updates across multiple files. Changes include correcting typographical errors, clarifying descriptions of API calls and networking requirements, updating JSON payload examples for accuracy, improving section titles and bullet points, and expanding the list of supported TLS versions for data encryption in transit. The modifications do not alter any exported or public code entities and are limited to documentation content and structure. Assessment against linked issues
Possibly related PRs
Suggested reviewers
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (2)
modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc (1)
451-459: Description/variable mismatch – “network ID” vs “cluster ID”The sentence says “get the network ID”, but the example captures
.operation.resource_idintoREDPANDA_ID, which is the cluster ID.
Either update the prose or the jq filter; otherwise readers will export the wrong ID and subsequent commands will fail.Suggested fix:
-. Make a Cloud API call to create a Redpanda cluster and get the network ID from the response in JSON `.operation.metadata.network_id`. +. Make a Cloud API call to create a Redpanda cluster and get the cluster ID from the response in JSON `.operation.resource_id`.If you really need
network_id, capture it separately:export REDPANDA_NETWORK_ID=$(curl … | jq -r '.operation.metadata.network_id')modules/networking/pages/dedicated/gcp/configure-psc-in-api.adoc (1)
82-99: Example JSON is syntactically invalid – trailing comma will break copy-paste."gcp_private_service_connect": { "enabled": true, "consumer_accept_list": <consumer-accept-list> }, <-- trailing comma }Remove the comma or add a following key to keep the sample valid:
- } -} + } +}Leaving invalid JSON in docs frustrates users following the quick-start.
🧹 Nitpick comments (3)
modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc (1)
454-456: Minor bash escape issueThere’s a stray backslash after
"accept: application/json":-H "accept: application/json"\The trailing space makes the line continuation unnecessary; remove the backslash for clarity.
- -H "accept: application/json"\ + -H "accept: application/json" \modules/get-started/pages/cluster-types/serverless.adoc (1)
83-86: Consider splitting the long bullet back into two.A single bullet now contains two distinct points (“supports the Kafka API” and “works with all Kafka clients”). Separate bullets improve scan-ability:
-* Redpanda Serverless supports the Kafka API. Serverless clusters work with all Kafka clients. See xref:develop:kafka-clients.adoc[]. +* Redpanda Serverless supports the Kafka API. +* Serverless clusters work with all Kafka clients. See xref:develop:kafka-clients.adoc[].modules/get-started/pages/cluster-types/byoc/gcp/vpc-byo-gcp.adoc (1)
45-50: Placeholder correction LGTM, but tighten variable naming.Good catch changing
ipv2→ipv4.
While you’re here, align the placeholder prefix for Pods and Services so they’re visually parallel:- --secondary-range <secondary-ipv4-range-name-for-pods>=10.0.8.0/21,<secondary-ipv4-range-name-for-services>=10.0.1.0/24 + --secondary-range <secondary-ipv4-range-name-for-pods>=10.0.8.0/21,\ +<secondary-ipv4-range-name-for-services>=10.0.1.0/24(The back-slash keeps the command readable on two lines.)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
modules/ROOT/nav.adoc(1 hunks)modules/get-started/pages/cloud-overview.adoc(1 hunks)modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc(1 hunks)modules/get-started/pages/cluster-types/byoc/gcp/vpc-byo-gcp.adoc(1 hunks)modules/get-started/pages/cluster-types/serverless.adoc(1 hunks)modules/manage/pages/monitor-cloud.adoc(1 hunks)modules/networking/pages/aws-privatelink.adoc(1 hunks)modules/networking/pages/dedicated/gcp/configure-psc-in-api.adoc(2 hunks)modules/networking/partials/psc-api2.adoc(1 hunks)modules/security/pages/cloud-encryption.adoc(1 hunks)
🧰 Additional context used
🧠 Learnings (5)
📓 Common learnings
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#334
File: modules/networking/partials/psc-api2.adoc:15-16
Timestamp: 2025-06-18T21:02:38.074Z
Learning: In the Redpanda Cloud documentation system, cross-reference anchors using the format `#patch-/v1/clusters/-cluster.id-` work correctly for referencing API endpoints, even with dashes instead of curly braces around parameter names.
modules/get-started/pages/cluster-types/serverless.adoc (1)
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#261
File: modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc:46-50
Timestamp: 2025-04-18T19:43:32.991Z
Learning: In the Redpanda documentation using AsciiDoc format, explanatory text that provides additional information about a step should not be formatted as a separate numbered step. Instead, it should appear as regular text with bullets (using ** syntax) for any sub-points.
modules/networking/pages/aws-privatelink.adoc (1)
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#334
File: modules/networking/partials/psc-api2.adoc:15-16
Timestamp: 2025-06-18T21:02:38.074Z
Learning: In the Redpanda Cloud documentation system, cross-reference anchors using the format `#patch-/v1/clusters/-cluster.id-` work correctly for referencing API endpoints, even with dashes instead of curly braces around parameter names.
modules/networking/partials/psc-api2.adoc (1)
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#334
File: modules/networking/partials/psc-api2.adoc:15-16
Timestamp: 2025-06-18T21:02:38.074Z
Learning: In the Redpanda Cloud documentation system, cross-reference anchors using the format `#patch-/v1/clusters/-cluster.id-` work correctly for referencing API endpoints, even with dashes instead of curly braces around parameter names.
modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc (3)
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#334
File: modules/networking/partials/psc-api2.adoc:15-16
Timestamp: 2025-06-18T21:02:38.074Z
Learning: In the Redpanda Cloud documentation system, cross-reference anchors using the format `#patch-/v1/clusters/-cluster.id-` work correctly for referencing API endpoints, even with dashes instead of curly braces around parameter names.
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#267
File: modules/manage/pages/maintenance.adoc:91-92
Timestamp: 2025-04-25T01:41:57.162Z
Learning: The notification timeline for Redpanda Cloud deprecations has been deliberately removed from the documentation, even though the PR summary mentioned a 180-day advance notice period.
Learnt from: david-yu
PR: redpanda-data/cloud-docs#338
File: modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc:74-75
Timestamp: 2025-06-24T03:31:29.345Z
Learning: User david-yu indicated that the standard Azure zones format using plain numbers like "1", "2", "3" is not valid for their specific Azure BYOVNet setup, suggesting there may be specific tooling or API requirements that expect region-prefixed zone names like "centralus-az1".
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - rp-cloud
- GitHub Check: Header rules - rp-cloud
- GitHub Check: Pages changed - rp-cloud
🔇 Additional comments (7)
modules/manage/pages/monitor-cloud.adoc (1)
76-78: No broken xrefs detected—heading rename is safeI ran ripgrep across all *.adoc files (including xref and anchor shorthand patterns) for
monitor-for-health-and-performanceand found no matches. The updated heading won’t introduce any 404s.modules/networking/partials/psc-api2.adoc (1)
44-46: Good catch: invalid JSON comma removedRemoving the trailing comma after
"enabled": falsefixes the JSON payload so thePATCHrequest will no longer be rejected by the API.modules/ROOT/nav.adoc (1)
333-335: Navigation order tweak acknowledgedMoving
logger/about.adocbeneathredpanda/about.adocreads more naturally and keeps related component docs grouped.modules/security/pages/cloud-encryption.adoc (1)
24-26: TLS 1.3 addition looks accurateStating support for both TLS 1.2 and 1.3 aligns with the cipher suite list below and current platform capabilities.
modules/get-started/pages/cloud-overview.adoc (1)
53-56: Wording looks good – no further action needed.The revised sentence (“take full control of the networking lifecycle”) is concise and reads well.
modules/networking/pages/aws-privatelink.adoc (1)
46-50: Typo fix acknowledged.“cluser” → “cluster” brings the doc back to professional spelling.
modules/networking/pages/dedicated/gcp/configure-psc-in-api.adoc (1)
37-42: Value update looks correct.
"DEDICATED"→"TYPE_DEDICATED"matches the enum used elsewhere.
micheleRP
force-pushed
the
DOC-1487-apply-coderabbit-cloud-docs-suggestions
branch
from
23f1841 to
681e01d
Compare
Description
This pull request includes a variety of documentation updates and corrections across multiple files, focusing on improving clarity, fixing typographical errors, and ensuring consistency in terminology. Below are the most important changes grouped by theme:
Terminology and Typographical Fixes:
modules/networking/pages/aws-privatelink.adoc.modules/networking/pages/dedicated/gcp/configure-psc-in-api.adoc. [1] [2]Content Clarifications:
modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc.modules/security/pages/cloud-encryption.adoc.Formatting and Structural Adjustments:
modules/manage/pages/monitor-cloud.adocfor better readability.These updates improve the overall accuracy and readability of the documentation.
Resolves https://redpandadata.atlassian.net/browse/DOC-1487
Review deadline:
Page previews
Checks