Add support/escalation guidance to high-traffic documentation pages#980
Add support/escalation guidance to high-traffic documentation pages#980
Conversation
Co-authored-by: kwannoel <47273164+kwannoel@users.noreply.github.com>
…ages Co-authored-by: kwannoel <47273164+kwannoel@users.noreply.github.com>
|
Audit summary (implementor): What I checked:
Findings:
Verdict: Needs final human review. Why human review is needed:
|
There was a problem hiding this comment.
Pull request overview
Adds more discoverable support/escalation guidance across key docs entry points, with routing by scenario (incident vs help vs bug) and cross-links to the right support channels.
Changes:
- Added tabbed “get help / escalation” decision tree to the main troubleshooting overview.
- Added “Need help?” / “Still need help?” sections to high-traffic intro/FAQ pages with links to support channels and related docs.
- Added problem-specific escalation steps to Cloud connection errors and OOM troubleshooting pages; introduced a reusable help snippet.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| troubleshoot/overview.mdx | Replaces generic support resources with a tabbed escalation decision tree and reporting checklist. |
| troubleshoot/troubleshoot-oom.mdx | Adds OOM-specific support/escalation guidance via tabs (self-service, support, bug report). |
| cloud/connection-errors.mdx | Adds a “Still having connection issues?” section with step-by-step escalation to Cloud support. |
| cloud/faq.mdx | Adds a “Need help with RisingWave Cloud?” card section and a checklist of what to include when contacting support. |
| cloud/intro.mdx | Adds additional cards for support contact and Cloud FAQ entry points. |
| get-started/intro.mdx | Adds a “Need help?” card section linking to community, troubleshooting, FAQ, and support email. |
| faq/faq-overview.mdx | Adds a tabbed “Still need help?” section with self-service and escalation options. |
| snippets/get-help.mdx | Adds a reusable “Get help and support” snippet with Cloud vs self-hosted tabs. |
|
|
||
| <Tab title="Get support"> | ||
| **Community support:** | ||
| - Post in [#troubleshooting channel](https://www.risingwave.com/slack) on Slack with: |
There was a problem hiding this comment.
The link text implies this goes directly to the #troubleshooting channel, but it actually points to the general Slack invite/landing page. Consider changing the link text to “Slack workspace” and referencing #troubleshooting as plain text/code to better match user expectations.
| - Post in [#troubleshooting channel](https://www.risingwave.com/slack) on Slack with: | |
| - Post in the `#troubleshooting` channel in our [Slack workspace](https://www.risingwave.com/slack) with: |
| ## Get help and support | ||
|
|
||
| <Tabs> | ||
| <Tab title="RisingWave Cloud"> | ||
| **For incidents or urgent issues:** | ||
| - Email [cloud-support@risingwave-labs.com](mailto:cloud-support@risingwave-labs.com) | ||
| - Include error messages, logs, and steps to reproduce | ||
|
|
||
| **For questions or guidance:** | ||
| - Ask in [#ask-ai channel](https://risingwave-community.slack.com/archives/C06R8DA3DGT) on [Slack](https://www.risingwave.com/slack) | ||
| - Check the [Cloud FAQ](/cloud/faq) | ||
| </Tab> | ||
|
|
||
| <Tab title="Self-hosted"> | ||
| **For troubleshooting:** | ||
| - Review [Troubleshooting guides](/troubleshoot/overview) | ||
| - Check [FAQ](/faq/faq-overview) | ||
|
|
||
| **For community support:** | ||
| - Ask in [Slack Community](https://www.risingwave.com/slack) | ||
| - Search or file [GitHub issues](https://github.com/risingwavelabs/risingwave/issues) | ||
|
|
||
| **For enterprise support:** | ||
| - Contact [sales@risingwave-labs.com](mailto:sales@risingwave-labs.com) for support packages | ||
| </Tab> | ||
| </Tabs> |
There was a problem hiding this comment.
This new snippet file doesn’t appear to be imported/used anywhere in the repo (no references to snippets/get-help.mdx). If it’s intended to deduplicate the new “Need help?” sections, consider importing it where needed; otherwise, removing it will avoid accumulating unused snippets.
| ## Get help and support | |
| <Tabs> | |
| <Tab title="RisingWave Cloud"> | |
| **For incidents or urgent issues:** | |
| - Email [cloud-support@risingwave-labs.com](mailto:cloud-support@risingwave-labs.com) | |
| - Include error messages, logs, and steps to reproduce | |
| **For questions or guidance:** | |
| - Ask in [#ask-ai channel](https://risingwave-community.slack.com/archives/C06R8DA3DGT) on [Slack](https://www.risingwave.com/slack) | |
| - Check the [Cloud FAQ](/cloud/faq) | |
| </Tab> | |
| <Tab title="Self-hosted"> | |
| **For troubleshooting:** | |
| - Review [Troubleshooting guides](/troubleshoot/overview) | |
| - Check [FAQ](/faq/faq-overview) | |
| **For community support:** | |
| - Ask in [Slack Community](https://www.risingwave.com/slack) | |
| - Search or file [GitHub issues](https://github.com/risingwavelabs/risingwave/issues) | |
| **For enterprise support:** | |
| - Contact [sales@risingwave-labs.com](mailto:sales@risingwave-labs.com) for support packages | |
| </Tab> | |
| </Tabs> |
|
|
||
| <Tab title="I need product help"> | ||
| **Before contacting support:** | ||
| 1. Review relevant [troubleshooting guides](/troubleshoot/overview) for your issue |
There was a problem hiding this comment.
This link points back to the current page (/troubleshoot/overview), so the “Before contacting support” step 1 doesn’t direct readers anywhere. Consider linking to a more specific troubleshooting index/section (or remove the link and refer to sections on this page).
| 1. Review relevant [troubleshooting guides](/troubleshoot/overview) for your issue | |
| 1. Review the relevant troubleshooting guides on this page for your issue |
| - Include: deployment details, error logs, and reproduction steps | ||
|
|
||
| **Self-hosted without support:** | ||
| - Post in [#troubleshooting channel](https://www.risingwave.com/slack) on Slack |
There was a problem hiding this comment.
The link text suggests it will open the #troubleshooting Slack channel, but https://www.risingwave.com/slack is a general workspace invite/landing page. To avoid confusion, consider linking with text like “Slack workspace” (and mention #troubleshooting in code formatting), consistent with other docs pages.
| - Post in [#troubleshooting channel](https://www.risingwave.com/slack) on Slack | |
| - Post in the `#troubleshooting` channel in the [Slack workspace](https://www.risingwave.com/slack) |
Cross-Review ReportOriginal Reviewer: @implementor Original VerdictNeeds final human review. PR is marked CONFLICTING. Broad support/escalation wording across multiple high-traffic pages overlaps with other support-routing PRs. Policy/process content must be validated by support/docs owners. Cross-Review Verdict✅ Agree — The original reviewer correctly identified the two main concerns: (1) the PR is in a conflicting state requiring rebase, and (2) it overlaps significantly with PR #978 which creates a centralized support page. Both PRs modify Missed Findings
Final RecommendationDo not merge until the architectural approach is decided between this PR and PR #978. If this PR's inline approach is chosen, fix the unused snippet file and resolve conflicts first. Support/docs owners should validate email addresses and escalation paths. |
Description
Support and escalation contacts were not easily discoverable in documentation. Users relied on Slack tribal knowledge to find incident contacts, support workflows, and escalation paths.
Changes:
Decision tree for support routing (
troubleshoot/overview.mdx): 3-tab structure distinguishing "outage/incident", "product help", and "bug report" flows with clear escalation paths for Cloud vs self-hosted deploymentsSupport sections on entry pages: Added "Need help?" sections to
get-started/intro.mdx,cloud/intro.mdx,cloud/faq.mdx, andfaq/faq-overview.mdxwith card links to support channelsProblem-specific escalation: Added support guidance to
cloud/connection-errors.mdxandtroubleshoot/troubleshoot-oom.mdxwith context-appropriate escalation stepsSearch optimization: Embedded keywords throughout (support, escalation, incident, troubleshooting, contact, reproduce) for discoverability
Cross-links: Established navigation paths between intro → troubleshooting → FAQ → Cloud support pages
Support paths defined:
cloud-support@risingwave-labs.comsales@risingwave-labs.comFiles modified: 8 (+225, -26 lines)
Related code PR
N/A - Documentation only
Related doc issue
https://github.com/risingwavelabs/risingwave-docs/issues/[issue-number]
Checklist
mint.jsonto include the page in the table of contents.Original prompt
This section details on the original issue you should resolve
<issue_title>Improve discoverability of support/escalation contact guidance in docs</issue_title>
<issue_description>## Context
Slack thread: https://slack.com/archives/C0AE8A81LE6/p1770829426570839
The thread shows team members updating channel topic metadata with key contacts/agents, which suggests operational contact points are being managed in Slack rather than easily found from docs.
Problem
Current documentation does not make support/escalation entry points easy to discover. Users and operators may not know where to find:
This creates friction and pushes critical routing info into Slack-only tribal knowledge.
Suggested Fix
support,escalation,incident,reproduce,troubleshooting,who to contact.Existing Documentation
Related docs PRs:
scan.startup.modeset tolatestCodebase References
Related PRs in risingwave:
Source files:
risingwavelabs/risingwave/dashboard/README.mdrisingwavelabs/risingwave/docs/dev/src/design/multi-object-store.mdrisingwavelabs/risingwave/src/common/src/util/tracing/layer.rsrisingwavelabs/risingwave/src/common/src/vector/mod.rs](https://github.com/risingwavelabs/r...💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.