When to use it
Troubleshooting content lives in two places, and the recipe covers both:
-
Inline, on the page where the failure happens — the default. Use a “What if…” callout inside a how-to or an FAQ accordion at a feature page’s end. The inline form keeps the same internal shape, compressed:
What if login fails with
Error: no workspace selected? The CLI is authenticated but not pointed at a workspace. Runhookline workspace use <name>and retry. -
A dedicated troubleshooting page per product area, once inline entries pass ~5 or the same failure spans multiple pages.
It is not:
- A how-to. A how-to pursues a goal; troubleshooting recovers from a failure. “Set up delivery alerts” is a how-to even though it involves problems.
- An error reference. If the product has stable error codes, a complete per-code catalog is reference material (one entry per code, uniform template — see the reference recipe); the troubleshooting page covers symptoms, multi-cause problems, and the narrative “it’s slow / it’s flaky” cases codes don’t capture. Small products merge the two; say which page owns what.
- A global FAQ. Questions with known answers get placed on the page that should have answered them. A troubleshooting page is organized by failure, not by question.
Title & description
- Entry titles: the verbatim symptom — ideally the exact error message. “Error: signature timestamp outside tolerance” beats “Signature problems” in search, in retrieval, and in a sidebar scan. Long messages: keep the distinctive substring, trimmed to roughly 70 characters, with ASCII
...marking the cut. Message type (“Error:”, “Warning:”) stays in the title. Symptom-shaped entries without a message get observable phrasing: “Deliveries succeed but arrive twice.” - Page title: “Troubleshooting area” — e.g. “Troubleshooting delivery.”
- Description formula: “Fixes for the common failures in area, by symptom.”
Scaffold this page
Install the recipe — your coding agent reads the full skeleton and checklist and adapts them to your product:
npx @cloudflare/nimbus-docs add content-troubleshootingyarn dlx @cloudflare/nimbus-docs add content-troubleshootingpnpm dlx @cloudflare/nimbus-docs add content-troubleshootingbunx @cloudflare/nimbus-docs add content-troubleshootingComponent guidance
- Fenced blocks for the verbatim message — the match target for search, readers, and retrieval. Show one realistic concrete instance, variable values included (
skew 512s > 300sdemonstrates the mechanic; the stable substring still matches searches). Never paraphrase the error; never elide its distinctive part. - Bold Cause/Fix/Verify labels (or a fixed sub-heading trio) — the uniform internal order is what lets a panicking reader skip straight to Fix.
- Accordions fit the inline form (FAQ-style at a feature page’s end); on dedicated pages, entries stay open — hidden symptoms are unfindable, and the page exists to be scanned.
- Doesn’t fit: Cards, marketing tone, and reassurance without a fix (“this is usually harmless” — then say when it isn’t).
Ending
Dedicated pages end with Still stuck? — the escalation path with a collect-this-first list. It’s the type’s honesty clause: a troubleshooting page that implies completeness strands the reader with the one failure it missed.
Thresholds
- Inline until ~5 entries, then a dedicated page — and leave a link behind at the inline site.
- Most common failure first; a data-loss failure jumps the queue. Ordering is triage.
- Every workaround states its cost and its permanent alternative. A workaround presented as a fix is how tech debt gets documented into permanence.
Links & freshness
Every Cause links to the concept explaining the mechanism; every multi-step Fix links to (or is) a how-to. Feed this page from support requests and community questions — it’s the one type whose backlog writes itself — and prune entries when the product fixes the underlying failure: a fix for a problem that no longer exists sends readers hunting for a setting that’s gone. Stamp the page’s lastVerified date when you sweep it against the current release.
Agent notes
- This is the type agents retrieve by exact string match — the verbatim error in a fenced block is the whole game. Show a realistic concrete instance; the stable substring carries the match. Elision (ASCII
...) belongs only in titles of long messages, and never on the distinctive part. - Structure Cause → Fix as declaratives an agent can execute; “check your configuration” is not a fix,
hookline test-event --endpoint <id>is. - Keep each entry fully self-contained — entry N will be retrieved without entry N−1 and without the page intro.
Checklist
Advisory — self-review for author or agent, never a build gate:
- Entry titles are verbatim messages or observable symptoms (long ones trimmed to the distinctive substring, ~70 chars)
- Every entry with a message shows it in a fenced block, as one concrete instance; symptom-only entries state the observable behavior in their first line
- Fixed internal order: Symptom → Cause → Fix (→ Verify); multi-cause entries pair each cause with its confirmation and its fix
- Workarounds labeled, costed, and paired with the permanent fix
- Most common failure first; data-loss failures jump the queue
- Dedicated page ends with Still stuck? + collect-this-first list
- Causes link to concepts; multi-step fixes link to how-tos
- Entries pruned when the underlying failure is fixed;
lastVerifiedstamped on sweep