トラブルシューティング

トラブルシューティングページは、読者が遭遇する失敗ごとに原因と解消手順を対応付け、質問ではなく症状で整理します。トーンは案内的で、率直に、解決志向にします。

トラブルシューティングは 2 か所に置きます。失敗が起きるページ上の「もし〜なら」コールアウトまたはアコーディオン（インライン）と、インライン項目がおおよそ 5 件を超えるか、同じ失敗が複数ページにまたがるときの、製品エリアごとの専用ページです。読者が失敗から復帰できるようにするために使います。次のものではありません。

• ハウツー。 ハウツーは目標を追います。トラブルシューティングは失敗からの復帰です。
• エラーリファレンス。 コードごとの完全な一覧はリファレンスです。このページは、症状、原因が複数ある問題、エラーコードでは拾えない「遅い、または不安定」なケースを扱います。
• 全体向け FAQ。 トラブルシューティングページは質問ではなく失敗で整理します。

全体の比較は コンテンツタイプ を参照してください。

• ページタイトル: 「Troubleshooting」のあとに製品、機能、エリアを続けます。例: 「Troubleshooting delivery」。
• 項目タイトル: 症状をそのまま書きます。可能ならエラーメッセージそのものです。「Error: signature timestamp outside tolerance」のほうが、「Signature problems」より検索とサイドバーの走査に向きます。長いメッセージは、特徴的な部分おおよそ 70 文字までに切り、切り口は ASCII の "..." で示し、「Error:」などのメッセージ種別は残します。メッセージがない症状は、観察できる言い方にします。例: 「Deliveries succeed but arrive twice」。
• Description: そのエリアのよくある失敗を、症状ごとに直すページであることを述べます。

Nimbus の troubleshooting レシピを使って、このページを生成します。コーディングエージェントがページのひな形と自己レビュー用チェックリストを取得し、製品に合わせて調整します。

npx @cloudflare/nimbus-docs add content-troubleshooting

yarn @cloudflare/nimbus-docs add content-troubleshooting

pnpm @cloudflare/nimbus-docs add content-troubleshooting

レシピが出力する frontmatter を Cloudflare のスキーマに合わせて調整します。レシピが出力する type などの汎用フィールドではなく、pcx_content_type と products を設定します。

• フェンス付きコードブロック に、エラーメッセージを原文どおり置きます。検索、読者、取得の照合対象です。現実的な具体例を 1 件、実値付きで示します。メッセージを言い換えたり、特徴的な部分を省略したりしないでください。
• Cause、Fix、Verify を太字のラベル にし、どの項目も同じ内部順にします。焦っている読者が対処へ直行できます。
• Details のアコーディオンは、機能ページ末尾のインライン形式に向きます。専用ページでは項目を開いたままにします。隠れた症状は見つからないためです。
• 向かないもの: Cards、マーケティング調、対処のない安心材料だけ。

pcx_content_type: troubleshooting
products:
  - product-a
  - product-b

詳細は pcx_content_type を参照してください。

項目は頻度順に並べ、いちばん多い失敗を先にします。データ損失の失敗は順番を飛ばして先頭へ上げます。製品エリアの項目がおおよそ 5 件を超えるまでインラインのままにし、超えたら専用ページへ移して、元の場所にはリンクを残します。回避策には必ずコストを書き、恒久的な代替手段の名前を挙げます。専用ページの末尾は「まだ解決しない場合」セクションにし、エスカレーション経路と、先に集める情報の一覧を置きます。これはこのタイプの誠実さの条項です。完全であるかのように書くと、漏れた 1 件の失敗で読者が行き詰まります。

• 項目は自己完結させます。 各項目は単体で成立するように書きます。項目 N は、直前の項目もページ導入もなしに取得されるためです。症状、原因、対処をすべて書きます。
• 実行可能な対処にします。 原因と対処は、エージェントが実行できる断定文にします。「設定を確認してください」は対処ではありません。hookline test-event --endpoint <id> のような具体的なコマンドが対処です。
• 症状は原文どおり。 エラーメッセージは、フェンス付きブロックに具体例 1 件として原文どおり示します。検索、読者、取得が、その文言そのもので照合できるようにします。