Docs: improve approachability, discoverability, and content depth#39
Merged
Docs: improve approachability, discoverability, and content depth#39
Conversation
The home page "Get Started" button linked to /getting-started which resolved to the Cookiecutter reference page, not the actual quickstart guide. Now quickstart.md owns /getting-started (nav_order 2) and Cookiecutter.md is demoted to /cookiecutter-reference (nav_order 10). Also adds a manual setup section (no cookiecutter) to the Getting Started page and updates all 8 cross-references across howto pages and integrations.md to point to the new cookiecutter-reference URL.
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR reorganizes and expands site documentation: renames Cookiecutter and Quickstart pages (and permalinks), adds a Getting Started manual setup, introduces multiple new how‑to/reference pages (config-reference, production, debugging, vtprotobuf, data‑builder), adds vtprotobuf and Kubernetes content, and updates front‑matter and internal links across many docs. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 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 |
…prove SEO - Add comprehensive Configuration Reference page with all 40+ env vars organized by category (server, gRPC, TLS, Prometheus, OTLP, etc.) - Add Production Deployment guide with K8s manifests, health probes, Prometheus ServiceMonitor, gRPC load balancing, graceful shutdown tuning - Expand Debugging guide: Delve usage, gRPC debug env vars, interceptor chain inspection, common error patterns and solutions - Expand data-builder guide: graph visualization, error handling, testing patterns with Replace, common pitfalls (cycles, missing inputs, types) - Improve SEO meta descriptions on FAQ, Packages, howto index pages - Update USING.md config table to match actual defaults and link to full config reference
ankurs
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
quickstart.md (1)
297-308: Consider adding a prerequisite reminder for buf in the manual setup section.The manual setup section uses
bufcommands (lines 371-372) but doesn't mention that buf must be installed first. While buf is listed in the Prerequisites section at line 25, that section is contextually focused on the cookiecutter approach. Users jumping directly to "Alternative: Manual Setup" might miss this requirement.📋 Suggested improvement
## Alternative: Manual Setup (No Cookiecutter) If you prefer to set up a project manually without cookiecutter, here's the minimal path: +{: .note } +You'll need **[buf](https://buf.build/docs/installation)** installed for protobuf code generation. + ### 1. Initialize your module🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@quickstart.md` around lines 297 - 308, Add a short prerequisite note under the "Alternative: Manual Setup (No Cookiecutter)" section reminding users to install buf before running the buf commands referenced later; specifically, update the Manual Setup section (the "Alternative: Manual Setup (No Cookiecutter)" heading) to include a one-line reminder such as "Ensure buf is installed (see prerequisites) or install via https://buf.build" so readers who skip to manual setup see the requirement before the buf commands are used.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@quickstart.md`:
- Around line 391-413: The myService type is missing the required Stop() method
needed to satisfy the core.CBService interface; add a Stop() method on myService
(matching the signature expected by core.CBService) that performs any necessary
cleanup and returns an error (or nil) so the type implements InitGRPC, InitHTTP
and Stop; update the myService type to include Stop() (used when calling
cb.SetService(&myService{})) ensuring the method name and signature exactly
match the interface definition in core.CBService.
---
Nitpick comments:
In `@quickstart.md`:
- Around line 297-308: Add a short prerequisite note under the "Alternative:
Manual Setup (No Cookiecutter)" section reminding users to install buf before
running the buf commands referenced later; specifically, update the Manual Setup
section (the "Alternative: Manual Setup (No Cookiecutter)" heading) to include a
one-line reminder such as "Ensure buf is installed (see prerequisites) or
install via https://buf.build" so readers who skip to manual setup see the
requirement before the buf commands are used.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4e5e6e9b-32e0-4b6d-a9c5-5e6aa89c198f
📒 Files selected for processing (10)
Cookiecutter.mdhowto/APIs.mdhowto/Log.mdhowto/Tracing.mdhowto/gRPC.mdhowto/interceptors.mdhowto/signals.mdhowto/swagger.mdintegrations.mdquickstart.md
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reorganizes the docs “Getting Started” flow so the home page button and navigation land users on the intended first-run guide, while demoting the cookiecutter details into a separate reference page and updating cross-links accordingly.
Changes:
- Renames/repurposes the Quickstart page as “Getting Started” and moves it to
/getting-started, adding a manual setup alternative. - Moves the cookiecutter page to
/cookiecutter-referenceand updates references across how-to/integrations docs. - Adds new reference-style docs pages (Production Deployment, Configuration Reference) and enriches several page descriptions.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| quickstart.md | Renamed to “Getting Started”, changed permalink to /getting-started, added manual setup path. |
| Cookiecutter.md | Retitled/repositioned as “Cookiecutter Reference” at /cookiecutter-reference with guidance back to Getting Started. |
| integrations.md | Updates [ColdBrew cookiecutter] reference to new cookiecutter-reference URL. |
| howto/APIs.md | Updates cookiecutter reference link to new anchor URL. |
| howto/signals.md | Updates cookiecutter reference link to new anchor URL. |
| howto/swagger.md | Updates cookiecutter reference link to new URL. |
| howto/interceptors.md | Updates cookiecutter reference link to new URL. |
| howto/gRPC.md | Updates cookiecutter reference link to new URL. |
| howto/Tracing.md | Adds description and updates cookiecutter reference link. |
| howto/Log.md | Updates cookiecutter reference link. |
| howto/index.md | Improves How To index description. |
| howto/data-builder.md | Adds sections on graph visualization and testing guidance. |
| howto/Debugging.md | Adds Delve + debugging guidance and troubleshooting patterns. |
| howto/production.md | New production deployment guide (Kubernetes, probes, Prometheus, shutdown tuning, etc.). |
| config-reference.md | New environment variable configuration reference page. |
| USING.md | Aligns config variable names/defaults and links to new config reference page. |
| Packages.md | Improves page description metadata. |
| FAQ.md | Improves page description metadata. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+163
to
+167
| | Endpoint | Purpose | Kubernetes probe | | ||
| |----------|---------|------------------| | ||
| | `/healthcheck` | Liveness — is the process alive? | `livenessProbe` | | ||
| | `/readycheck` | Readiness — can it accept traffic? | `readinessProbe` | | ||
|
|
There was a problem hiding this comment.
The Markdown table here starts with || ... instead of | ... |, which will render as an extra empty first column (or misrender) in most Markdown processors. Update the table rows to use single leading/trailing pipes so the table renders correctly.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
howto/production.md (1)
355-355: Align checklist wording with the shutdown formula used earlier.Line 355 says “shutdown + healthcheck wait duration”, but earlier guidance uses
SHUTDOWN_DURATION_IN_SECONDS + GRPC_GRACEFUL_DURATION_IN_SECONDS. Consider using the same terms here to avoid ambiguity.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@howto/production.md` at line 355, Update the checklist item to use the same terminology as earlier by replacing “shutdown + healthcheck wait duration” with the explicit formula `SHUTDOWN_DURATION_IN_SECONDS + GRPC_GRACEFUL_DURATION_IN_SECONDS` so readers see the same variables used previously and avoid ambiguity; reference the same constants shown earlier to ensure consistency across the doc.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@howto/data-builder.md`:
- Around line 280-299: The test mutates a package-level Plan `p` via `Replace`,
which can leak state across tests; change the test to use a fresh local plan
instance (create a new Plan instead of using the package-level `p`) and call
`Replace` and `Run` on that local variable (e.g., use a local `p := NewPlan()`
or equivalent factory) so the `Replace` of `BuildPriceAdjustment` is isolated to
this test and cannot affect other tests; ensure all calls reference the local
`p` (for `Replace`, `Run`, and result handling).
In `@howto/production.md`:
- Line 367: Remove the unused markdown link reference "[Configuration
Reference]: /config-reference" from the document (or alternatively add a
corresponding in-body reference link that uses "[Configuration Reference]" so
the reference is actually referenced); locate the literal reference line
"[Configuration Reference]: /config-reference" in the file and either delete
that line or add an in-body link like "[Configuration Reference]" where it
should be used.
---
Nitpick comments:
In `@howto/production.md`:
- Line 355: Update the checklist item to use the same terminology as earlier by
replacing “shutdown + healthcheck wait duration” with the explicit formula
`SHUTDOWN_DURATION_IN_SECONDS + GRPC_GRACEFUL_DURATION_IN_SECONDS` so readers
see the same variables used previously and avoid ambiguity; reference the same
constants shown earlier to ensure consistency across the doc.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: e44364af-69ba-410c-998d-42de40012fe6
📒 Files selected for processing (8)
FAQ.mdPackages.mdUSING.mdconfig-reference.mdhowto/Debugging.mdhowto/data-builder.mdhowto/index.mdhowto/production.md
✅ Files skipped from review due to trivial changes (5)
- Packages.md
- howto/index.md
- FAQ.md
- config-reference.md
- howto/Debugging.md
- Add new howto/vtproto.md covering the custom gRPC codec, three-level fallback chain, buf code generation setup, VT features (clone, equal, pool), and when to disable - Add "Fast Serialization" to home page feature table - Add vtprotobuf section to integrations page with setup instructions - Link config reference DISABLE_VT_PROTOBUF to the new howto page
- Add vtprotobuf to "Don't Repeat Yourself" integrations list on home page - Add FAQ entry explaining vtproto vs standard protobuf with comparison table, performance characteristics, and link to howto guide
- Update home page tagline to mention Kubernetes-native and 12-factor - Add "Kubernetes-native" row to home page feature table - Add "Design Principles" section to architecture page with 12-factor alignment table mapping each principle to ColdBrew's implementation - Add FAQ entry: "Is ColdBrew designed for Kubernetes?"
…ure table - Add 5 zero-config features to "What You Get Out of the Box": Swagger/ OpenAPI UI, pprof profiling, gRPC reflection, HTTP gzip compression, and GOMAXPROCS auto-tuning via automaxprocs - Add FAQ entry: "How do I use grpcurl or Postman with my ColdBrew service?" with grpcurl examples and DISABLE_GRPC_REFLECTION reference
There was a problem hiding this comment.
🧹 Nitpick comments (2)
FAQ.md (2)
75-93: Qualify the vtprotobuf performance claim to avoid overpromising.The “2–3x faster” statement on Line 77 is useful, but it should be explicitly labeled as workload-dependent (and ideally point to benchmark context) to avoid being interpreted as a guaranteed result.
Proposed wording tweak
-[vtprotobuf](https://github.com/planetscale/vtprotobuf) (by PlanetScale) generates optimized `MarshalVT()`/`UnmarshalVT()` methods for protobuf messages that are typically **2–3x faster** than standard `proto.Marshal()` with fewer allocations. +[vtprotobuf](https://github.com/planetscale/vtprotobuf) (by PlanetScale) generates optimized `MarshalVT()`/`UnmarshalVT()` methods for protobuf messages that are often faster than standard `proto.Marshal()` with fewer allocations (exact gains are workload-dependent).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@FAQ.md` around lines 75 - 93, Update the performance claim in the FAQ paragraph that states "2–3x faster" for vtprotobuf to qualify it as workload-dependent and link or reference benchmark context; specifically edit the sentence mentioning vtprotobuf performance so it reads something like "typically ~2–3x faster in our benchmarks for certain workloads" and/or add a parenthetical noting that results vary by message shape and workload and pointing readers to a benchmark or the vtprotobuf README for details; ensure the change targets the vtprotobuf description paragraph (the lines mentioning "2–3x faster") so the claim is not presented as a guaranteed outcome.
134-150: Add a TLS grpcurl example next to plaintext commands.The current examples are great for local dev, but adding one TLS-based invocation would prevent copy/paste confusion for production users where plaintext is disabled.
Suggested addition
```bash # List all services grpcurl -plaintext localhost:9090 list @@ # Call a method grpcurl -plaintext -d '{"msg": "hello"}' localhost:9090 mypackage.MyService/Echo + +# TLS example (production-like) +grpcurl -cacert ca.pem api.example.com:443 list</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@FAQ.mdaround lines 134 - 150, Add a TLS-based grpcurl example to the "How
do I use grpcurl or Postman with my ColdBrew service?" FAQ section so users have
a production-ready invocation; keep the existing plaintext examples and append a
single TLS example line showing use of -cacert and host:port (e.g., "grpcurl
-cacert ca.pem api.example.com:443 list") and mention using the appropriate
server name and cert path, and update the surrounding text to note that TLS
examples are for production where plaintext is disabled.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In@FAQ.md:
- Around line 75-93: Update the performance claim in the FAQ paragraph that
states "2–3x faster" for vtprotobuf to qualify it as workload-dependent and link
or reference benchmark context; specifically edit the sentence mentioning
vtprotobuf performance so it reads something like "typically ~2–3x faster in our
benchmarks for certain workloads" and/or add a parenthetical noting that results
vary by message shape and workload and pointing readers to a benchmark or the
vtprotobuf README for details; ensure the change targets the vtprotobuf
description paragraph (the lines mentioning "2–3x faster") so the claim is not
presented as a guaranteed outcome.- Around line 134-150: Add a TLS-based grpcurl example to the "How do I use
grpcurl or Postman with my ColdBrew service?" FAQ section so users have a
production-ready invocation; keep the existing plaintext examples and append a
single TLS example line showing use of -cacert and host:port (e.g., "grpcurl
-cacert ca.pem api.example.com:443 list") and mention using the appropriate
server name and cert path, and update the surrounding text to note that TLS
examples are for production where plaintext is disabled.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `bf3f4773-b045-49f7-ba53-67535c199868` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 360b2ef890f817e6c55f9d787556b7c49bd59d9c and de63bcf4da24cb2e8a25be0892ab7372afe0261b. </details> <details> <summary>📒 Files selected for processing (3)</summary> * `FAQ.md` * `Index.md` * `architecture.md` </details> <details> <summary>✅ Files skipped from review due to trivial changes (2)</summary> * architecture.md * Index.md </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
- Add "Self-Documenting APIs" section with pipeline diagram showing how one proto file generates gRPC stubs, REST gateway, OpenAPI spec, and vtprotobuf via buf generate - Add table mapping each output to its self-documenting endpoint - Show proto annotation example with both HTTP and OpenAPI metadata - Update home page feature row to mention Swagger docs
Replace the 30-line Go code block with a concise proto annotation example that better showcases ColdBrew's "define once, get everything" story. The full Go example is on the Getting Started page.
…ickstart, FAQ - Home page: update "Define Once" closing line to highlight typed Go interfaces and compile-time enforcement - Architecture: add "Type-Safe by Design" subsection with ASCII diagram showing proto → interface → compiler enforcement flow - Quickstart: add note after make generate explaining why the compiler errors until you implement the new method - FAQ: add "How does ColdBrew ensure API consistency?" entry covering compile-time enforcement, gateway sync, and OpenAPI generation
There was a problem hiding this comment.
🧹 Nitpick comments (2)
Index.md (1)
38-38: Linkgrpcuifor consistency with other tool references.
grpcuiis currently plain text while nearby tools are link-backed. Consider linking it to improve scanability and parity.Suggested small doc tweak
-| **gRPC Reflection** | Server reflection enabled by default — works with [grpcurl], grpcui, and Postman | +| **gRPC Reflection** | Server reflection enabled by default — works with [grpcurl], [grpcui], and Postman |[grpcurl]: https://github.com/fullstorydev/grpcurl +[grpcui]: https://github.com/fullstorydev/grpcui [automaxprocs]: https://github.com/uber-go/automaxprocs🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@Index.md` at line 38, The docs row for "gRPC Reflection" currently links grpcurl and Postman but leaves grpcui as plain text; update that table cell (the "gRPC Reflection" row) to make "grpcui" a hyperlink like the others by replacing the plain text token grpcui with a markdown link to the grpcui project (e.g., [grpcui](https://github.com/fullstorydev/grpcui)) so all tools in that cell are consistently link-backed.FAQ.md (1)
102-102: Avoid absolute wording (“impossible”) in contract guarantees.Consider softening this sentence to avoid overclaiming in edge cases (e.g., custom routes outside generated surfaces).
Suggested wording adjustment
-This means it's impossible to have a documented endpoint that doesn't exist, an undocumented endpoint that does exist, or an HTTP route that doesn't match the gRPC method signature. +This makes it highly unlikely to have a documented endpoint that doesn't exist, an undocumented endpoint that does exist, or an HTTP route that drifts from the gRPC method signature within generated surfaces.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@FAQ.md` at line 102, The sentence in FAQ.md uses absolute language ("impossible") about contract guarantees; change it to a softened phrasing that acknowledges edge cases (e.g., "generally ensures", "strongly discourages", or "in normal usage, prevents") so it doesn't overclaim (e.g., replace "This means it's impossible to have..." with "This generally ensures you won't have..." or "This prevents, in normal usage, a documented endpoint that doesn't exist..."), keeping the rest of the sentence about the proto file being the contract and the compiler/gateway/docs enforcing it intact.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@FAQ.md`:
- Line 102: The sentence in FAQ.md uses absolute language ("impossible") about
contract guarantees; change it to a softened phrasing that acknowledges edge
cases (e.g., "generally ensures", "strongly discourages", or "in normal usage,
prevents") so it doesn't overclaim (e.g., replace "This means it's impossible to
have..." with "This generally ensures you won't have..." or "This prevents, in
normal usage, a documented endpoint that doesn't exist..."), keeping the rest of
the sentence about the proto file being the contract and the
compiler/gateway/docs enforcing it intact.
In `@Index.md`:
- Line 38: The docs row for "gRPC Reflection" currently links grpcurl and
Postman but leaves grpcui as plain text; update that table cell (the "gRPC
Reflection" row) to make "grpcui" a hyperlink like the others by replacing the
plain text token grpcui with a markdown link to the grpcui project (e.g.,
[grpcui](https://github.com/fullstorydev/grpcui)) so all tools in that cell are
consistently link-backed.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: fa43ac64-718a-4df1-b754-7c3e808eccb0
📒 Files selected for processing (4)
FAQ.mdIndex.mdarchitecture.mdquickstart.md
✅ Files skipped from review due to trivial changes (1)
- architecture.md
🚧 Files skipped from review as they are similar to previous changes (1)
- quickstart.md
…ields - Architecture: expand Trace ID interceptor row to mention HTTP header and proto field extraction, propagation to logs and Sentry/Rollbar - Tracing howto: add "Trace ID Propagation" section covering HTTP header mechanism (x-trace-id), proto field mechanism (GetTraceId/GetTraceID), destination table (logs, error reports, request context), and note clarifying separation from OpenTelemetry trace context - FAQ: add "How does trace ID propagation work?" entry
- Replace /quickstart/ with /getting-started/ (permalink changed) - Update /getting-started/ expected title to "Getting Started" - Add /cookiecutter-reference/ and /config-reference/ to top-level pages - Add /howto/vtproto/ and /howto/production/ to howto pages
- Make grpcui a hyperlink in the gRPC Reflection feature table row - Soften "impossible" to "strongly prevents" in FAQ API consistency entry
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Fix Delve port in Debugging guide: use 2345 (Delve default) instead of 9090 (gRPC port) to avoid conflicts - Use fresh local plan in data-builder test example to avoid shared mutable state across tests - Remove unused [Configuration Reference] link ref from production guide
This was referenced Apr 4, 2026
3 tasks
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
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
Comprehensive docs overhaul to make ColdBrew more approachable and discoverable.
Navigation & onboarding
/getting-started— home page "Get Started" button lands on the right page/cookiecutter-reference(nav_order 10) with redirect notego mod init+ minimalmain.goNew pages
Expanded guides
Kubernetes & 12-factor messaging
SEO & discoverability
Test plan
bundle exec jekyll serve— verify navigation order and all links resolve/getting-started(quickstart page)[ColdBrew cookiecutter]links →/cookiecutter-reference/config-reference,/howto/production,/howto/vtprotoSummary by CodeRabbit