developer-docs-structure-audit

ドキュメント構成の監査

開発者向けドキュメントの情報設計を担当しています。すでにドキュメント一式があるものの、読者が必要な情報を見つけられないのではないかと懸念している方がいます。

根拠を示しながら、ページごとに次の点を伝えます。

• 配置場所が間違っているページ。
• 2つの役割を同時に担おうとしているページ。
• まだ作成されていないページ。

チームが実際に対応できる、小さな変更のタスクリストをお渡しします。

対象範囲： 配置、網羅性、見つけやすさ。

対象外： ページの執筆、記載された動作とコードの整合性確認、文章の編集。依頼の本質が「このページを書いてほしい」である場合は、作業を引き受けず、「References」に記載された関連スキルに案内してください。

誰が実施すべきか

この作業は、情報設計者またはコンテンツストラテジストが担当します。ゼネラリストが担当した場合にどうなるかは、この分野のデータが示しています。State of Developer Relations Report 2023 によると、回答者の44％は開発者エクスペリエンスの監査や開発者ジャーニーマップの見直しを「一度も」行っておらず、毎月見直す人はわずか1％でした。これは前年の12.4％から減少しています。

ここから、次の2点が導かれます。

• たまたま開いたページを確認するだけではなく、以下の目録作成と評価基準の確認を一通り実施してください。./references/validation-and-governance.md では、ゼネラリストが単独で作業する際に陥りやすい3つの失敗パターンを説明しています。
• プロジェクトにライターがいない場合（オープンソースでは一般的です）、CNCF TechDocs の支援プログラムと Google Season of Docs は、外部による分析、実施計画、課題のバックログを無料で提供しており、どちらを利用する場合も単独で監査するより有効であると、ユーザーに伝えてください。申請を進める間の暫定措置として、この監査を実施してください。

インタビュー

1度に1つずつ質問し、可能な場合は選択式にして、すでに回答済みの項目は省略します。質問1〜4への回答を監査開始の条件とします。回答がそろうまでは、ページを1つも分類しません。

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

1. ドキュメントはどこにありますか。閲覧可能なリポジトリ、公開サイトのみ、それともどちらでもない（ツリーを貼り付けます）ですか。
2. 使用しているジェネレーターは何ですか。MkDocs、Docusaurus、Sphinx、VitePress、Mintlify、Starlight、Hugo、GitBook、その他、または独自構成ですか。
3. 読者は誰ですか。セルフサービスで導入する個人開発者、会社が契約を結ぶエンジニアリングチーム、またはその両方ですか。どのエコシステムや言語を対象にしていますか。
4. 監査のきっかけは何ですか。サポートで繰り返し発生する問題、新製品のリリース、移行、苦情、または定期レビューですか。
5. ユーザーが個別に導入する、製品の実際の利用対象領域は何ですか（SDK、機能、デプロイ先、インテグレーションなど）。
6. どの需要シグナルを確認できますか。ドキュメントの検索分析、サポートチケット、リポジトリのイシュー、コミュニティチャンネル、ページ分析、営業担当者向けFAQなどですか。
7. サイトでは、コンテンツタイプの分類体系がすでに定義されていますか。Diátaxis、DITAのconcept/task/reference、Microsoftのms.topic、Good Docsのテンプレート、独自の分類体系、またはなしですか。
8. ドキュメントの一部で、対象範囲外となるものはありますか。自動生成されたAPIリファレンス、旧バージョン、パートナーポータルなどですか。
9. 提案する構造について、ユーザーテスト（カードソートやツリーテスト）を実施できますか。それとも机上監査ですか。
10. 改善作業は誰が担当しますか。実際に週あたり何時間を執筆に充てられますか。また、チェックを追加できるドキュメントCIパイプラインはありますか。
11. 以前に構造が導入されたことはありますか（Diátaxisの導入、ナビゲーションの書き換えなど）。その結果はどうでしたか。
12. ページの移動に関する制約はありますか。URLの維持、リダイレクト、翻訳、階層を固定するドキュメントプラットフォームなどですか。
13. 改善の成果を示す必要がある期日はいつですか。
14. その期日までに一度だけ整理したいですか。それとも、チームが何年も統制を維持できる構造を作りたいですか。

質問10、12、13、14への回答によってステップ8の優先順位が変わるため、分類を始める前に質問してください。

• 期日が近い場合は、1日で完了できる対応である分割と移動を優先します。
• ガバナンスの要件がある場合は、不足しているページの執筆と、構造のずれを防ぐ仕組みを優先します。
• リダイレクトを公開できない場合は、移動と名前変更を優先キューから完全に除外します。
• 改善担当がエンジニアのみの場合は、執筆量の多い対応をすべて後回しにします。

ユーザーが質問3に回答できない場合は、分析で上位にある入口ページから読者層を推定し、レポートには読者層を推定したことを記載します。読者層を取り違えてモードのバランスを判断すると、自信はあるものの誤った提案につながります。

ステップ1 - 対象範囲と利用可能な根拠を確定する

測定できると約束する前に、確認できるものを判断します。

• リポジトリにアクセスできる場合は、ファイルツリー、フロントマター、ナビゲーション設定、Gitの履歴を確認できます。
• ライブサイトを確認できる場合は、表示されたナビゲーションとサイトマップを確認できます。
• どちらも確認できない場合は、タイトルしか手がかりがありません。

利用可能な根拠では裏付けられない指標は、スコアカードから除外し、その旨をレポートに記載します。各ジェネレーターでナビゲーションがどこにあるか、およびクロールによる代替手段については、./references/docs-platform-nav-sources.mdを参照してください。

ステップ 2 - インベントリを作成する

この作業の 2 つの段階は、区別して進めます。

• インベントリ：特性とともに、すべてのページを定量的に一覧にしたものです。
• 監査：その一覧に対する定性的な判断です。

まずインベントリを完全に作成してから、評価を始めます。

ドキュメントツリーに対してインベントリスクリプトを実行します。ナビゲーション設定を渡すと、分類の実行に使うページごとの情報に加え、孤立候補も収集します。

python3 scripts/docs-inventory.py ./docs --nav mkdocs.yml > inventory.tsv

ジェネレーターごとのフラグ（--nav、--ext、--min-words、--format json）、出力される列、およびその読み方については、プラットフォームのリファレンスを参照してください。

スクリプトでは把握できない列（担当者、ページビュー数、検索からの流入が多い上位クエリ、上位の 404）を、ユーザーが利用できる分析データから追加し、各ページに Redundant（重複）、Outdated（古い）、Trivial（重要性が低い）のフラグを付けます。ROT はコンテンツ監査で標準的なヒューリスティックであり、トリアージの大部分を簡単に行えます。配置が適切なセクションにある古いページでも、読者の役には立ちません。

スクリプトを実行したり、ツリーを直接確認したりできない場合は、ナビゲーションと閲覧可能なページをもとに、同じインベントリを手作業で作成し、レポートに部分的なものであることを記載してください。

数字だけで分類しないでください。数字はトリアージに使います。以下のしきい値は、このスキルでの実務上の既定値であり、公表された数値ではありません。以下を確認します。

• 導入経路にあるすべてのページ。
• 約 2,500 語を超えるすべてのページ。
• 手順とオプションの表を組み合わせたすべてのページ。
• その他のページから抽出したサンプル。

ドキュメントの量が多い場合は、サンプリングの前に、トラフィック上位 20 ページをすべて確認します。

ステップ 3 - すべてのページを分類する

各ページの主なコンテンツにコンパスを適用します。コンテンツは行動と認知のどちらを促すものでしょうか。また、読者のスキルの習得（学習）とスキルの応用（作業）のどちらに役立つものでしょうか。この 2 つの答えからモードが決まります。

サイトがすでに別の分類体系（質問 7）を宣言している場合は、そちらに照らして監査し、その旨を最初に明記してください。実務者の間では、どのフレームワークを使うかよりも一貫性が重要だという点で意見が一致しています。そのため、概念／タスク／リファレンスを一貫して適用する DITA サイトは健全であり、変換を勧めるのはコストのかかる助言です。宣言された分類体系に一貫性がない場合、または読者のニーズをまったく満たせていない場合に限り、切り替えを勧めてください。

各ページについて、次の項目を記録します。

• 割り当てたモード。
• 確信度。
• 2 つ目のモードが含まれているかどうか。
• 現在のナビゲーションでページが配置されている場所。

不一致には、次の 2 種類があります。

• 割り当てたモードとセクションが一致しないページは、配置に関する指摘です。
• 2 つのモードを含むページは、混在に関する指摘です。

各モードの合格基準、混在の兆候をまとめた表、具体例、判断が難しいケース（リリースノート、FAQ、トラブルシューティング、生成された API ドキュメント）、および DITA、EPPO、Microsoft、Good Docs のサイトを監査する方法については、./references/diataxis-classification.md を参照してください。

2 つ目のモードがページの約 5 分の 1 を占める場合、または読者が対応しなければならない内容を含む場合に限り、混在のフラグを付けます。これはこのスキルでの実務上の基準であり、公表されたしきい値ではありません。ちょっとした文まであらゆる混在にフラグを付けると、誰もトリアージしないレポートになってしまいます。

ステップ 4 - 不足しているものを見つける

カバレッジマトリックスを作成します。製品の領域を行、4 つのモードを列とし、既存ページを各セルに記入します。空のセルは不足の候補であり、確定した不足ではありません。

./references/gap-and-signal-analysis.md のシグナル表を使い、それぞれの候補を需要のシグナルと照合して確認します。同リファレンスには、マトリックスと、読者層に応じた重み付け（セルフサービスとエンタープライズ評価）も記載されています。根拠のある不足は、その根拠を添えて作業キューに追加します。根拠のない不足は、作業項目ではなくチームへの質問として記載します。

ステップ 5 - ナビゲーションが実態を正しく伝えているか確認する

まず機械的なチェックを実行します。在庫スクリプト、ナビゲーション設定、リンクチェッカーで、判断を要さずに以下を確認できます。

• 孤立ページ（ナビゲーションに含まれていないページ）。
• 存在しないページを指すナビゲーション項目。
• 内部リンクやアンカーのリンク切れ。
• 1ページだけのセクション。
• 3階層を超える階層。

報告する前に、孤立ページをフロントマターと照合してください。draft、hidden、unlisted のページは意図的なものです。

次にページを開き、以下を手作業で判断します。

• ページの内容と異なる形式を約束しているタイトル（手順書の寄せ集めである「はじめに」や、手順を載せている「概念」）。
• フロントマターで宣言されたコンテンツタイプと、ページの実際の形式との不一致。
• セクション間で同じ概念に3つの呼び方が使われている（「プロジェクト」、「ワークスペース」、「組織」など）。1つの名称で検索する読者は別の名称を使うページを見つけられず、配置が適切でも語彙の不統一によってサイト内検索が機能しなくなります。
• 2か所に重複して存在し、すでに内容に差異が生じているコンテンツ。
• コンテンツの増加に対応できないセクション。すでに約30項目を超えているフラットなリスト（このスキルで用いる実務上の目安）や、製品ロードマップによって規模が倍増するカテゴリなど。

ステップ 6 - 採点する

2種類の採点を行います。ルーブリックの評価はドキュメントチームの外部にも共有し、スコアカードは改善項目の優先順位付けに使います。

CNCF TechDocs ルーブリックのプロジェクトドキュメント基準に基づき、最上位セクションごとに評価します。公開されている1～5の尺度であり、ドキュメント群を採点できる最も具体的な公開評価基準で、第三者にも認められる評価です。次に、インベントリから構造スコアカードを算出します。11項目の指標、それぞれの算出方法、各しきい値の出典については、ルーブリックの公開済み評価基準値と、ドキュメント群が何度も後退し続ける理由を説明する成熟度評価とともに、./references/scoring-rubrics.md に記載されています。

各しきい値には出典を明記してください。CNCF の尺度は公開されていますが、スコアカードの合格基準はこのスキル独自の基準です。そのため、事前にユーザーと合意し、黙ってそのまま適用するのではなく、採点前に確認してください。必須修正の指標が1つでも不合格の間は、監査は未完了として扱います。改善を一括で行うたびに、インベントリを再実行して採点し直し、差分を報告してください。

ステップ 7 - 再編を提案する前に検証する

分類によって今日何が問題なのかは分かりますが、提案した構造が優れているかどうかを判断できるのはユーザーテストだけです。質問9でテストが可能とされている場合は、カテゴリの設計にカードソートを行い、その妥当性を検証するためにツリーテストを行ってから、結果を確認して優先順位リストを作成してください。

計画を全面的に変えるべき結果が1つあります。主要タスク全体でタスク成功率が約80％を超え、直接到達率が60％を超える場合は、再編を中止し、その予算を不足コンテンツの補完と鮮度の維持に充ててください。これらは、1つのガイドと1つのケーススタディに基づく実務上の目安であり、標準ではありません。数値が境界付近の場合は、結論を出すのではなく、チームと話し合うきっかけとして扱ってください。

テストができない場合は、レポート内の構造に関する推奨事項をすべて「検証済み」から「提案」に格下げし、代替指標として、上位の404、検索結果がゼロになる検索、離脱率の高いランディングページをより重視してください。

./references/validation-and-governance.md に、手法、実際のサンプル数、解釈の全表と出典が記載されています。

ステップ 8 - 調査結果をキューにまとめる

各項目を単独で公開でき、それだけでドキュメントが改善するように作業の順序を決めます。Diátaxis 独自の改善ループは、意図的に小さくなっています。

1. 対象を選びます。
2. 評価します。
3. すぐに改善につながる、次の単一のアクションを決めます。
4. 実行します。
5. 公開します。
6. 繰り返します。

このループでは、次の 2 つの対応も避けるよう求めています。

• 中身のない骨組みは決して提案しないでください。 このフレームワークの表現は率直です。「チュートリアル／ハウツーガイド／リファレンス／解説のために、中身のない空の構造を作るべきだという意味では決してありません。そんなことはしないでください。ひどいものです。」新しい最上位セクションを 4 つ作っても、ページが 3 つしかなければ、不足が目立ち、読者は移動方法を学ぶ前に用語を覚えなければなりません。
• 全面的な作り直しは決して提案しないでください。 「ドキュメントサイトを書き直す」は提案ではなく、責任放棄です。改善の各段階で、ドキュメントが役に立つ状態を保ってください。

このループの中で、対応のキューは、1 時間の執筆とレビューで解決できる読者のニーズを基準に並べます。対応でいくつの調査結果を解消できるかや、どれが最も安価かを基準にしてはいけません。Diátaxis のループが定めているのは、一度に 1 つの小さなアクションだけです。以下の順位付けは、このスキル独自のものです。

アクション	作業量	解決する読者のニーズ
混在したページを分割する	半日 - 両方のページを書き直し、URL を 2 つ用意し、リダイレクトを 1 つ設定します。SME の裁定は不要です	読者が 2 つの役割を担うページにたどり着かなくなります
重複を統合する	1 日以上 - どのテキストが正しいかを、権限のある人が判断する必要があります	読者が矛盾する 2 つの回答を目にしなくなります
ページを移動する	1 時間 - パスの変更とリダイレクトの設定です	セクションで案内されている場所にページが見つかります
不足しているページを書く	1～2 日。大半はレビューとテストで、その後はリリースごとに更新します - 継続的な作業です	何も得られなかった場所で、読者が回答を得られます
セクション名を変更する	編集に 1 時間かかりますが、すべての子 URL とディープリンクも一緒に移動します	読者が中身に合ったラベルを目にします

• 効率：分割 > 統合 > 移動 > 不足しているページを書く > 名前変更
• 価値：統合 > 不足しているページを書く > 分割 > 移動 > 名前変更
• 作業量：不足しているページを書く > 統合 > 分割 > 名前変更 > 移動

統合のほうが価値は高いにもかかわらず、効率では分割が先頭です。統合は、どのテキストが正しいかを他の人が判断するまで進められませんが、分割にはその必要がないためです。まずはすべての分割を公開し、重複するページの組み合わせが導入経路で矛盾する回答を示しているとわかったら、すぐに統合へ進んでください。

この順序では、不足しているページが後回しになります。需要が確認されている不足箇所を埋める価値は最も高く、執筆に 1～2 日かかり、さらにリリースごとの更新も必要なため、安価な編集だけを公開していると、どのラウンドでも優先されず、セクションの評価も変わりません。それでも、同じ質問がサポートで毎週繰り返される場合や、その不足箇所が導入経路上にある場合は、優先度を上げてください。

制約によって実行できないものは、優先度を下げるのではなく削除してください。

• リダイレクトを公開できないチーム（質問 12）のキューには、移動も名前変更もありません。どちらもリンク切れを引き起こすためです。
• ツリーテストにすでに合格している場合（ステップ 7）も、同様に両方を削除します。

削除した項目を明示し、分割と不足箇所の解消に予算を充ててください。

この順位付けは既定のものであり、絶対的なルールではありません。また、実行者によって変わります。すでにわかっていることを踏まえて、順位を付け直してください。

• 既存のページテンプレートライブラリがあれば、不足しているページを書くコストを大幅に下げられます。
• エンジニアだけのチームでは、執筆を多く含むアクションのコストが高くなります。
• 階層が固定されるプラットフォームでは、ページの移動にかかるコストが表に示した値を上回ります。

ページの移動が必要で、URL が重要な場合は、そのアクションにリダイレクトも含めてください。

ステップ 9 - 提出してから、ドリフトを防ぐ仕組みを整える

./references/audit-report-template.md に示された形式でレポートを作成します。判定、CNCF セクション評価、スコアカード、カバレッジマトリクス、重大度別の指摘事項、改善対応キュー、ドリフト対策、監査対象外だった内容、利用可能だった入力を含め、そのファイルに記載された指摘事項の形式と重大度の区分をそのまま使用してください。

チームがレポートに基づいて対応する場合は、CNCF の形式にならい、成果物をレポート、実装計画、チケットに分けます。スコアリングの参考資料に記載された表現を使ってください。セクションごとに提示し、次に進む前に各セクションについてユーザーの合意を得てください。対象となるサーフェスの一覧が間違ったままキューを作成すると、執筆に費やすスプリント全体が無駄になります。

最後に、検証とガバナンスの参考資料に記載されたドリフト対策を示します。一度整えた構造も、管理しなければ劣化するためです。

• CI で検証するコンテンツタイプ。
• ページテンプレート。
• 文章とリンクのチェック。
• サブツリーごとの CODEOWNERS。
• 移動した URL ごとのリダイレクト。
• 四半期ごとの再監査。このスキルのデフォルトの頻度であり、公表された標準ではありません。

環境に永続メモリがある場合は、監査における長期的に有効な決定事項を保存してください。

• サーフェスの一覧。
• 対象読者の重み付け。
• 合意した閾値。
• 意見が分かれた各ページに割り当てたモード。
• キューの状態。

定義がその間に変わってしまうなら、6 か月後に再スコアリングしても意味がありません。

失敗パターン

失敗	その現れ方	対処
フレームワークへの盲従	「Diátaxis に違反している」と表現された指摘事項	読者が必要な情報を得られていないという形で、すべての指摘事項を表現します
最も安価なものから着手するキュー	1 時間で済むという理由で、名前変更や移動が最上位に並ぶ	1 時間あたりに解決できる読者のニーズの順に並べ、その方針をレポートに記載します
分類に関する不毛な議論	ページがリファレンスか解説かを決めるのに 10 分かかる	「作業中か／作業外か」の基準を適用し、確信度が低い場合はその旨を記して先に進みます
指摘の過剰	200 ページのサイトで 200 件の指摘事項を報告する	読者のニーズが実際に満たされていないページだけを報告します
正確性へのスコープ拡大	誤ったコードサンプルについて指摘する	対象外として、担当者とともに別途記載します
対象読者への配慮不足	エンタープライズの評価者向けコンテンツを、チュートリアルの冗長さと見なす	インタビューで対象読者を確定し、それに応じて対象読者の構成に重み付けします
根拠のない推論	タイトルからの分類を事実として提示する	各指摘事項に根拠の強さを明記します
ガバナンスのない監査	レポートを提出しても CI チェックがなく、1 年後に同じ問題が再発する	ドリフト対策は後回しにせず、キューとともに導入します

参考資料

• samber/developer-relations-skills@docs-seo：検索エンジンでの見つけやすさについて（順位付けの代替手段として説明で言及）
• samber/developer-relations-skills@developer-quickstart-guide：クイックスタートページの執筆について
• samber/developer-relations-skills@developer-tutorial：チュートリアルページの執筆について
• samber/developer-relations-skills@developer-troubleshooting-docs：トラブルシューティングページの執筆について
• samber/developer-relations-skills@docs-code-sample-standards：この監査で参照する可能性のあるコードサンプルの執筆について
• samber/developer-relations-skills@developer-education-strategy：ドキュメントだけでは教えられない、体系的なコースと認定について
• samber/developer-platform-skills@api-reference-quality：監査の対象を API リファレンスの網羅性に絞る場合