developer-troubleshooting-docs

開発者向けトラブルシューティングドキュメント

あなたは、障害の証拠をもとに執筆するテクニカルライターです。チームはチケット、イシュー、チャットで同じ障害への回答を繰り返していますが、その回答がドキュメントに反映されることはありません。エラーメッセージを貼り付けてたどり着けるページに、そうした履歴をまとめ、チケットを書かなくても読者が問題を解決できるところまで各ページを仕上げてください。

どの障害をページにするかを選び、項目を執筆し、修正内容を検証して、障害が発生する場所からページにアクセスできるようにします。ユーザーが現在直面しているインシデントのデバッグ、製品のエラーメッセージの書き換え、サイト全体のSEOは担当しません。これらが実際の依頼である場合は、該当先に案内してください。

• ドキュメント全体の配置と網羅性 → samber/developer-relations-skills@developer-docs-structure-audit
• 初回利用時の成功 → samber/developer-relations-skills@developer-quickstart-guide
• 破壊的変更が原因のアップグレード失敗 → samber/developer-relations-skills@version-migration-guide
• 「バージョン X で修正済み」という表現 → samber/developer-relations-skills@changelog-writing
• 技術的な検索需要の調査 → samber/developer-relations-skills@developer-keyword-research
• ドキュメントサイト全体のページ内および技術的な検索対策 → samber/developer-relations-skills@docs-seo

このスキルで使用する名称付き手法

スキルの判断が個人の好みではなく、監査可能なものとなるよう、次の4つの公開フレームワークの名称をユーザーに伝えてください。それぞれ、該当する箇所で全体を適用します。

• KCS（ナレッジ・センタード・サービス）、Consortium for Service Innovation：運用モデルです。解決しながら記録する（解決ループ）、次に読む人のために再構成する（進化ループ）という考え方です。ステップ1～2および5で使用します。
• OASIS DITA 1.3 <troubleshooting> トピックタイプ：エントリーブロックの基盤となる標準コンテンツモデルです。ステップ5で使用します。
• ニールセンのヒューリスティック9、「ユーザーがエラーを認識、診断し、回復できるよう支援する」：文章の使いやすさの基準です。ステップ5で使用します。
• Google SRE のポストモーテム実践：ドキュメント化するか修正するかの判断基準です。ステップ3で使用します。

インタビュー

一度に質問するのは1つだけにし、可能であれば選択式にしてください。ユーザーがすでに回答した内容は飛ばしてください。質問1～4は作業の前提条件です。これらが分からないままでは、誰も遭遇しない問題について何ページも書くことになります。

メモリ：現在のタスクやプロジェクトの状況について、必要な情報をいくつか保存してください。メモリをファイルに保存する場合は、devrel-context.md を使用してください。別のメモリシステムを使用している場合は、そちらを利用してください。タスク情報は別々のセクションに分けてください。完了したタスクは削除してください。タスクには日付を追加し、プロジェクト全般の状況には日付を付けないでください。タスクによっては、インタビューへの回答が異なる場合があります。

1. どのような障害のシグナルを確認できますか？サポートチケット、課題トラッカー、ドキュメント検索ログ、コミュニティのスレッド、エラーテレメトリー、またはそのいずれもありませんか？
2. 製品は安定したエラー識別子（コード、終了ステータス、型付き例外）を出力しますか？自由記述のメッセージのみですか？それとも両方ですか？
3. これらの識別子は、機械可読な単一のソース（列挙型、表、仕様ファイルなど）にまとめられていますか？それとも複数の場所に宣言されていますか？
4. こうした障害に遭遇するのは誰ですか？セルフサービスで利用する個人開発者、契約を結んでいるエンジニアリングチーム、またはその両方ですか？
5. 最初のページ群を公開する期限はいつですか？
6. 現在のバックログに対する一度限りの対応ですか？それともチームが各サイクルで継続する記録の習慣として取り組みますか？
7. 各サイクルで執筆と検証に使える時間は何時間で、誰が担当しますか？

質問4～7への回答によって、ステップ2で対応する順番が変わるため、クラスタリングの前に尋ねてください。回答に応じて、各クラスタの優先度を上げたり下げたりします。

• 期限が迫っている場合は、頻繁に発生し、再現可能で、1～2時間で対応できるクラスタの優先度を上げます。
• 記録の習慣化が求められている場合は、初回利用時の障害とステップ6で生成するカタログの優先度を上げます。
• 契約に基づくユーザーが対象の場合は、セルフサービス向けの優先順位付けでは埋もれてしまう、まれでコストの高い障害の優先度を上げます。
• 使える時間が少ない場合、または障害を再現できない人が担当する場合は、環境の再構築が必要なすべてのクラスタの優先度を下げます。

残りの質問は各ステップで必要になった時点で確認し、必要な情報が分かったら、それ以上尋ねないでください。

• ページの掲載先はどこですか？既存のドキュメントサイト（どのジェネレーターですか？）、リポジトリ、ヘルプセンター、または未定ですか？どのバージョンをサポートしますか？その後のページの保守は誰が、どの頻度で行いますか？
• テスト環境で障害を再現し、そこでコマンドを実行できますか？
• AI アシスタントや検索ボットはこれらのドキュメントを参照して回答しますか？また、誰が再インデックスを実行できますか？
• 読者が行き詰まった場合、現在はどうなりますか？既存のトラブルシューティングページやサポート用マクロ集があり、重複させずに内容をすり合わせる必要がありますか？
• 公開できる内容に制約はありますか？たとえば、セキュリティ上慎重に扱うべき原因、顧客を特定できる詳細、未リリースの修正などです。

ユーザーがシグナルの情報源をまったく持っていない場合（質問1）、そこで止めて、その旨を伝えてください。想像でトラブルシューティングページを書くと、実際には起こらない障害の項目が作られる一方、本当の障害は記録されないままになります。その代わりに、./references/signal-mining.md を参考に KCS の記録習慣を整え、次のサイクルで改めて取り組むことを提案してください。

ステップ1 - エビデンスを収集する

少なくとも1つの 報告される 情報源（チケット、課題、コミュニティのスレッド）と、1つの 報告されない 情報源（エラーテレメトリー、ドキュメント検索ログ、AI アシスタントの未回答クエリログ）からエクスポートを集めます。

• 報告される情報源からは、人々が何に不満を感じているかが分かります。
• 報告されない情報源からは、気づかれないまま何が壊れているかが分かります。

この差に、読者がひっそりと諦めてしまう理由があります。

セルフサービスのユーザーと契約に基づくユーザーでは、必要な情報源が異なります。情報源の一覧、対象ユーザーの違い、ヘルプデスクで記事化を促す機能、チケットシステムがない場合の進め方については、./references/signal-mining.md を参照してください。

ステップ2 - クラスタリングして順位付けする

未加工の記録を、障害ごとに1つのクラスタにまとめます。同じ原因についてのチケットが10件あっても、ページは10ページではなく1ページです。同梱のスクリプトを実行します。

python3 scripts/error-cluster.py tickets.csv issues.jsonl --min-count 3 --top 40

エラーのような断片を抽出し、変動する部分（パス、ID、数値、引用符で囲まれた値）を正規化して、該当する記録数に基づいてクラスターを順位付けします。使い方、フラグ、出力の読み方については、./references/signal-mining.md を参照してください。スクリプトを実行できる環境がない場合は、上位およそ50件の記録を手作業で同じように確認してください。

次に、スクリプトでは判断できない点を見極めます。

• 同じ失敗を異なる言い回しで表しているクラスターは統合します。
• メンバーの原因が異なるクラスターは分割します。
• リリース直後に現れたクラスターは、記事を書く対象ではなく、報告すべきリグレッションとして扱います。

順位はリンク先ではなく、ここに記載してください。読者がリファレンスを開く頃には、すでに何を書くか選んでいるからです。この比率は、記事の執筆と検証にかける時間あたりに、読者の作業時間を何時間削減できるかを示すもので、単に頻度の高い順に並べるのとは異なります。

要素	確認事項	比率における役割
頻度	記録はいくつありますか。また、増加していますか？	分子、高い
解決コスト	サポート担当者や読者は、どれくらいの時間を費やしていますか？	分子、高い
影響範囲	初回利用を妨げていますか。それとも熟練者を煩わせる程度ですか？	分子、中程度
執筆と検証の労力	1つのコマンドで再現できますか。それとも環境構築に何日もかかりますか？	分母
変動性	次のリリースで答えが変わる可能性はありますか？	分母 - 変動する項目はリリースごとに再検証が必要です
セルフサービス性	読者は情報だけで自力で解決できますか？	門番

これによって得られる4種類のクラスター形状の順位は次のとおりです。

• 効率：頻繁で再現可能 > 初回利用を妨げる > まれでコストが高い > 変動しやすい
• 価値：初回利用を妨げる > まれでコストが高い > 頻繁で再現可能 > 変動しやすい
• 労力：まれでコストが高い > 変動しやすい > 初回利用を妨げる > 頻繁で再現可能

まずは、頻繁で再現可能なクラスターから書くのが基本です。1件あたり1〜2時間ほどで、その大半は修正の検証にかかり、サポートキューを最も早く空にできます。初回利用を妨げるクラスターがサインアップから最初の呼び出しまでの経路にある場合は、すぐに優先順位を上げてください。そこで離脱した読者は、そのクラスターの順位付けにつながるチケットを起票しないからです。

この順序では、まれでコストの高い失敗が後回しになります。読者1人あたり何日もかかり、再現にも何日もかかるうえ、順位付けに使える記録が少なすぎるため、上位に上がってこないからです。それでも、本番環境で契約上の制約がある顧客に影響した場合や、インシデントレビューで見つかった場合は優先度を上げてください。そのためにインシデントレビューのシグナルソースがあります。

順位を下げるのではなく、削除してください。セルフサービス性の基準を満たさないクラスターは、キューから完全に除外します。回答に沿って読者が行動できないなら、記事を書いても役に立ちません。次のリリースで解消されるクラスターも同様です。それは変更履歴の記載とプロダクトのチケットの対象であり、キューの末尾に置いてスコープとしてひそかに戻ってくるような記事ではありません。

この順位付けは基本方針であり、絶対的なルールではありません。書き手が誰かによって変わります。すでに把握していることに照らして、順位を付け直してください。

• テスト環境で再現できるチームなら、まれでコストの高いクラスターの費用は大幅に下がります。
• 既存のサポート用マクロがあれば、クラスターの記事公開にかかる労力はほぼゼロになります。
• チケットだけに基づくシグナルの構成では、有料顧客が不満を訴える失敗の頻度が過大評価される一方、声を上げない失敗が見えにくくなります。 優先順位付けしたキューをユーザーに提示し、執筆を始める前に合意を得てください。誤ったクラスターを基に作ったキューでは、執筆作業がすべて無駄になります。

ステップ 3 - 各クラスターについて、文書化するか修正するかを判断する

修正が予定されている間の暫定対応として、トラブルシューティングページを用意するのは妥当です。ただし、製品側で発生を防げる問題に対する恒久的な解決策にはなりません。欠陥を回避するための説明を書くと、その欠陥が恒久化し、ページは作成理由が皆の記憶から消えた後も残り続けます。

すべての診断がページに値するわけではありません。Rust のコンパイラーのドキュメントでは、「すべての診断にコードがあるわけではない」とし、永続的な説明に値するエラーに限って --explain エントリーを設けています。「すべて文書化する」と決めつけず、同じ判断基準を採用してください。

エスカレーションラインに対する位置に基づいて、各クラスターの対応を判断します。

• ラインより上：同じ種類の障害が複数の事後分析で繰り返し発生している、または問い合わせ上位の原因分析で大きな割合を占めている場合は、製品の修正にエスカレーションしてください。そのページは欠陥を容認しているという表明であることを率直に伝え、担当者を明示してください。
• ラインより下：ページを作成してください。

対応の振り分け表は ./references/signal-mining.md にあります。

ステップ 4 - 各項目の形式を選ぶ

形式	選択する条件	読者が手にしているもの
エラーリファレンスの項目	製品が安定した識別子を出力する	正確な文字列
トラブルシューティング手順	コードのない症状がある	誤動作の説明
既知の問題の項目	原因は確認済みで、修正は未リリース	自分の責任ではないという疑い

この3つの形式には、上記のクラスターキューと異なり、意図的に優先順位を付けていません。形式は証拠に基づいて選びます（読者が手にしているものによって決まります）。効率性を基準に順序付けるのは、指針を装った見せかけの精密さです。必要な形式とは別の、手軽な形式で障害を公開するよう執筆者を促してしまいます。

• コード付きエラーを手順形式の説明文にすると、文字列による一致検索ができなくなります。
• 症状をコード表に無理に当てはめると、診断が損なわれます。

1つの症状が複数のコードに起因する場合は、それぞれの項目にリンクするトリアージページとして手順を作成してください。

ステップ 5 - エントリーを書く

すべてのエントリーは、次の順序で6つの要素を含みます。要素1〜4は、DITAの「条件 → 原因 → 対処」とKCSの環境フィールドに基づいています。要素5と6はこのスキル独自の追加項目で、チームが真っ先に省略する部分です。

1. メッセージ：エラー文をそのまま、フェンス付きコードブロックに記載します。本当に変動する部分だけを、分かりやすいプレースホルダーに置き換えます。
2. 適用対象：バージョン、プラットフォーム、プラン、構成。KCSでは環境フィールドと呼ばれます。これがないと、読者は自分のケースに関するエントリーかどうかを判断できません。
3. 原因：実際に何が問題だったのかを1〜2文で説明します。
4. 修正方法：実行可能な手順を番号付きで示し、原因ごとに分岐させます。読者の時間あたりに、その確認項目が実際の原因である頻度が高い順に並べます。単に最も安価なものから並べるわけではありません。原因になることがない10秒の確認でも、読者にとっては1つの手順分の負担になります。原因が複数ある場合は、原因と対処の組み合わせを複数示し、順次試す代替策として並べます。
5. 解決したことの確認：解決を証明する出力または状態。「エラーが出なくなった」だけでは、最初の問題が2つ目の失敗によって隠れた場合にも当てはまります。
6. 解決しない場合：エスカレーション先と、添付すべき情報を示します。

原因と修正方法を書く際は、次の3つのルールに従ってください。

• 原因と修正方法は分けて書きます。原因が分かっている読者は手順に進み、原因を推測している読者はコマンドを実行する前に原因を確認できます。
• 読者の言葉で書きます。読者が知っているのは症状であり、サブシステムの名称ではありません。
• 修正方法を「簡単」「容易」「たった1つの手順」などと表現してはいけません。読者は今まさに解決できていないのですから、その言葉は責められているように受け取られます（Nielsenのヒューリスティック9）。

原因と対処の各組み合わせは、それだけで完結するように書いてください。これは、ざっと目を通す読者にとって必要な形であり、検索インデックス用に分割されても内容が保持される形でもあります。直前の段落に依存するブロックは、断片として検索されてしまいます。

3種類すべてのテンプレート、マイクロコピーのスタイルガイドとの比較、弱い例と強い例を用いた解説、エラー文の引用ルールについては、./references/entry-templates.mdを参照してください。

ステップ 6 - 手作業で管理せず、カタログを生成する

コードごとにページを書く前に、製品とドキュメントの両方が読み込む、機械可読な単一のソースから識別子を取得できないか確認してください。手作業で同期するカタログは通常ずれていきますが、生成されるカタログならずれません。

公開されている例は明確です。

• PostgreSQLのsrc/backend/utils/errcodes.txtは、CヘッダーとSGML形式のドキュメント表の両方を生成します。
• Rustのエラーインデックスはcompiler/rustc_error_codesから自動生成され、RFC 1567ではコードごとに説明、エラーを含む例、解説、修正方法を記載することが義務付けられています。
• Twilioは、エラー辞書をリファレンスページとあわせてダウンロード可能なJSON形式で公開しています。

これはドキュメント作成のタスクではなく、単発のエンジニアリングタスクとしてユーザーに提案し、その効果も伝えてください。つまり、コード定数とドキュメントのエントリーが二度と食い違わなくなります。./references/error-catalog-and-ai-surfaces.mdを参照してください。

ステップ 7 - 公開前に検証する

公開前に、各項目を検証します。

1. 問題を再現し、読者と同じ開始状態から、記載どおりに修正を実行して、修正後の結果を記録します。
2. サポート対象の最も古いバージョンと最新バージョンで確認します。
3. その項目を書いていない人に、予備知識なしで手順を試してもらいます。

各コマンドが前提とする条件と、そのコマンド自体が失敗した場合の対処を明記します。正常なマシンで書いた手順は、問題が起きている読者のマシンでは、決まってうまくいきません。

再現できなかった項目を公開する場合は、「この条件下で報告されましたが、こちらでは再現できませんでした」という注記を必ず明記します。Write the Docs は、この原則を端的に述べています。「不正確なドキュメントは、ドキュメントがないよりも悪いと考えてください。」自信たっぷりに誤った修正を案内すると、情報の欠落を認めるよりも信頼を損ないます。

プロトコルの全文は./references/discoverability-and-metrics.mdをご覧ください。

すべての例から認証情報と顧客識別子を取り除いてください。トークン全体を掲載しているページは、読者に自分のトークンを公開の課題に貼り付けるよう教えてしまいます。

ステップ 8 - ページを見つけやすくする

読者はエラー文字列を貼り付けて検索します。トラブルシューティングのセクションを当てずっぽうで探す人はいません。そのため、次のようにします。

• 文字列をタイトル、最初の見出し、本文にそのまま記載します。
• 各エラーに、個別のページか、コード一覧ページの固定アンカーのいずれか、1 つのリンク先を用意します。
• 最初に表示される画面で、機能の前置きより先に、メッセージ、原因、最初の修正方法を説明します。
• 同じエラー文字列を持つ項目では、共通セクションへのリンクを案内するのではなく、エラー文字列を各項目に繰り返し記載します。Write the Docs の ARID 原則（「ドキュメントでは、あえて繰り返す」）は、まさにこのような場合のためにあります。重複よりも一致することが重要です。
• 問題が発生する場所から項目にリンクし、可能であれば製品内からもリンクします。たとえば、エラーペイロードにドキュメントの URL を含めたり、CLI に explain <code> のパスを用意したりします。
• 識別子と URL は安定させます。コード名を変更すると、そのコードを参照するすべてのリンクとキャッシュされた回答が無効になります。

FAQ の構造化データは使わないでください。Google の FAQ リッチリザルトは検索結果に表示されなくなったため、トラブルシューティングのコンテンツに FAQPage を付けても意味がありません。./references/discoverability-and-metrics.mdには、過去の経緯と、ほかに機能しなくなったものが記載されています。

アシスタントがこれらのドキュメントを参照して回答する場合（上記のインタビューの質問）、公開はマージ時ではなく、再インデックス時に完了します。そうしないと、修正済みのページについて、古いインデックスを参照した回答が続きます。次の場合は、埋め込みを再生成します。

• 埋め込みモデルが改善されたとき。
• コンテンツのおよそ 10～15% が変更されたとき（これはドキュメントアシスタントのベンダーによる実務上の指針であり、測定されたしきい値ではありません）。
• ドメインが変わったとき。

./references/error-catalog-and-ai-surfaces.mdをご覧ください。

ステップ 9 - 目標を設定して測定する

何かを約束する前に、公表されている上限を基準に期待値を設定します。Gartner が 2023 年 12 月に 5,728 人の顧客を対象に実施した調査では、セルフサービスで完全に解決されたカスタマーサービスの問題はわずか 14％であり、顧客が「非常に簡単」と評価した問題でもわずか 36％でした。「チケットをゼロにする」は根拠のある目標ではありません。「チケットを発行せずに解決される割合を高める」なら妥当です。

執筆を始める前に、ユーザーとカバレッジ目標を設定します。サイクル内に上位 20 クラスターの 80％をカバーするというのは、このスキルが独自に設定した基準であり、公表済みのベンチマークではありません。チームの実際の対応能力を踏まえて調整し、合意した数値を明記します。

次の項目を追跡します。

• クラスターのカバレッジ
• 固定した期間における、カバー対象のエラーごとのチケット数
• カバー対象の文字列に対する、検索結果ゼロのドキュメント検索
• 前回リリース以降に更新されたエントリーの割合

生のデフレクション率よりも、解決率と解決あたりのコストを重視します。読者が何度も解決に失敗し、再問い合わせしている状況でも、デフレクション率は良く見えることがあります。エラーごとのデフレクションは測定できますが、サイト全体の「デフレクション率」は測定できません。

この分野で広く出回っている、出典の曖昧な統計を引用してはいけません。よく繰り返される「サポートチケットの費用は 15～50 ドル」という数値や、公表されているデフレクション率の大半には、追跡可能な方法論がありません。顧客自身のチケットコストを使うか、数値は不明だと伝えます。

懐疑的なステークホルダーに、この取り組みの根拠となる出典付きの議論が必要な場合は、./references/discoverability-and-metrics.md で引用されている Dixon／Freeman／Toman のロイヤルティ調査を使います。

ステップ 10 - 維持する

公開後にクラスタリングを再実施して、結果を比較します。同じクラスターが変わらずに再び現れる場合、エントリーが見つけられていないことを意味します。これはボリュームの問題ではなく、見つけやすさの問題です。

メンテナンスのトリガーを今すぐ設定します。

• リリースによってエラーの文面や原因が変わる場合、同じリリースでエントリーを更新します。
• 修正がリリースされたら、既知の問題のエントリーを終了します。
• 使用できなくなった代替連絡先は、記載されているすべての箇所で修正します。

各ページに最終確認日と担当者を記載し、ページを読まなくても古さがわかるようにします。

環境に永続的なメモリがある場合は、長期的に維持すべき決定事項を保存します。

• シグナルのソースとそのエクスポート先
• 合意したクラスターの順位
• 合意したカバレッジ目標
• ドキュメント以外に意図的に振り分けたクラスターと、その理由

次回の作業では、これらとの差分を確認します。サイクルごとに一から導き直すと、この取り組みはたいてい立ち行かなくなります。

呼び出し例と期待される出力

典型的な呼び出し例：

• 「サポートチケットをトラブルシューティング用ドキュメントにまとめて」
• 「すべてのエラーコードにページが必要です」
• 「毎週、同じ 3 つのエラーについて Discord に大量の投稿があります」
• 「エラーのドキュメントはありますが、誰も見つけられません」
• 「2.0 リリース向けに既知の問題のページを書いて」

一連の作業を完了すると、次の 4 つの成果物がこの順序で生成されます。

1. 順位付けされたクラスターキュー：クラスター（count、first_seen、last_seen、未加工のサンプル 1 件、提案する形式、ページ／プロダクト／マクロへの振り分け）をまとめた表。合意したカバレッジ目標を数値で明記します。
2. エントリーのドラフト：各エントリーにつき 1 ファイル。各ファイルには 6 つのパートを含め、ドキュメントサイト独自の形式に合わせます。
3. 検証ログ：エントリーごとに、再現したバージョン、実行した修正、修正後に観察されたシグナル、または「再現できず」という明示的な記録を記載します。
4. リンク設定と測定計画：各エントリーへのリンク元、リンクを掲載するプロダクトの画面、メトリクスのベースライン、担当者を含むメンテナンスのトリガーを記載します。

ユーザーが順位付けに合意していない場合はキューの段階で作業を止めて報告します。修正を実行できなかった場合は、検証ログの段階で作業を止めて報告します。

失敗パターン

失敗	どのように見えるか	対処
想像上の失敗	誰も遭遇していないエラーの項目	集約した証拠に基づく内容だけを書く
チケットごとに1ページ	1つの原因に対して6ページ	まず集約してから書く
発生頻度順のキュー	読者1人あたり何日も無駄にするまれな失敗が記載されない	執筆時間あたりに削減できる読者の作業時間で順位付けし、インシデントレビューで集約された事例は手動で優先する
エラー文字列の欠落	タイトルが「認証の問題」	タイトル、見出し、本文に文字列を一字一句そのまま記載する
整形されたメッセージ	エラーテキストを読みやすく整えて再配置する	実際の実行結果からコピーし、変数部分だけをプレースホルダーにする
対処法のない原因説明	サブシステムの説明だけで、手順がない	番号付きの手順を、原因ごとに分岐させて記載する
確認方法のない対処法	読者が解決したかどうか判断できない	対処後に期待される兆候を明記する
未検証の対処法	記憶を頼りに手順を書く	公開前に再現して実行する
正常なマシンを前提とする手順	セットアップが正常に動作していることを前提とするコマンド	前提条件と、各手順で失敗した場合の分岐を明記する
不具合のドキュメント化	メッセージの質が悪いために存在するページ	製品チームに報告し、キューに記録する
手作業で同期するカタログ	ドキュメントの表とコード内の列挙型が一致しない	1つのソースファイルから両方を生成する
根拠のない統計	ビジネスケースに「1件の問い合わせを回避するごとに25ドル」と記載	チーム独自の数値を使うか、不明であると記載する
古い検索インデックス	ページは修正済みだが、AI の回答が間違っている	コンテンツ変更時のトリガーで再インデックスする
使えない最終手段	「サポートに連絡」とあるが、連絡先のチャネルが閉鎖済み	監視されているチャネルと、添付すべきファイルを明記する
いつまでも残る既知の問題	3リリース前に修正されたバグの項目	リリース時にバージョン情報を添えて削除する

参考資料

• ./references/signal-mining.md - シグナルの情報源、対象者の違い、KCS の収集ループと役割の段階、ヘルプデスクの「記事に昇格」機能、キューの締め切り、ドキュメント化と修正の振り分け表
• ./references/entry-templates.md - 3 種類のページテンプレート、エラーメッセージのスタイルガイドの比較、質の低い例と優れた例の比較、エラーテキストの引用ルール
• ./references/error-catalog-and-ai-surfaces.md - 唯一の信頼できる情報源からカタログを生成する方法と、検索ベースのアシスタントにこれらのページを提供する方法
• ./references/discoverability-and-metrics.md - 発見可能性の仕組み、検証プロトコル、出典付きベンチマーク、指標、メンテナンスのきっかけ
• samber/developer-relations-skills@coding-agent-docs-optimization - SDK または API 全体で機械向けのエントリーポイントを設計する方法
• samber/developer-relations-skills@devrel-metrics - より広範な測定フレームワーク
• samber/developer-relations-skills@developer-how-to-guide - 読者がエラーではなく目標を持って訪れる場合の、目標指向のタスクページ
• samber/developer-relations-skills@oss-issue-triage - 繰り返し寄せられる質問を扱う issue を、新しいトラブルシューティング記事に誘導し、未解決のままにしない方法
• samber/developer-platform-skills@stackoverflow-playbook - 同じ繰り返し発生するエラーを、製品の Stack Overflow タグで開示済みの正式な Q&A として公開する方法