doc-refine — テクニカルドキュメント読解体験最適化ガイド
レビューと書き換えの境界
まず、レビューと書き換えを区別します。レビューのみが要求された場合は、問題点と提案を提供します。明確に修正が要求された場合のみ、許可されたドキュメントを修正します。動作や事実の変更（表現の調整ではない）が伴う場合は、元の意図を保持し、確認が必要な部分を指摘します。
削減前の保護対象：技術的な動作、API/データ契約、前提条件と境界条件、セキュリティおよび法的警告、アクセシビリティの代替説明、有効なサンプル、ソースリンク、安定したアンカー。コード内に同じ動作が存在するだけでは、ドキュメントを削除する十分な根拠にはなりません。局所的に必要な繰り返しは、独立した読解を助けることがあります。
2つのチェック目標
すべての判断は、最終的に2つの質問に帰着します。
| 公理 | 自分に問いかける質問 | 一言で |
|---|---|---|
| ① 素早く見つける | 対象読者は目次と見出しから情報の場所を判断できますか？ | 道標が明確 |
| ② 各段落に用途がある | 削除した場合、タスクの完了、動作の理解、またはリスクの制御に必要な情報が失われますか？ | 情報が完全かつ簡潔 |
すべてのコンテンツに対してこの2つのチェックを実行します。①を満たさない → 見出しの変更、図表の追加、構造の調整を行います。 ②を満たさない → 保護項目と読者のタスクを確認し、統合または削減を提案します。ページ数を理由に必要なコンテンツを削除しないでください。
ワークフロー
1. 診断（まず全文を読み、急いで修正しない）
対象ドキュメントを通読し、セクションごとに問題を記録します。
- 見出しは番号がなくても内容を独立して伝えられますか？（いいえ → 公理 ① 違反）
- 同じロジック/ルールが2箇所以上に現れていますか？（はい → 公理 ② 違反）
- この動作説明は、読者が契約、制限、または結果を理解するのに役立ちますか？まず用途を判断し、「何か」「なぜ」で機械的に削除しないでください。
- 導入文は単なる繰り返しの前置きですか？表現を簡潔にできますが、その中のステップの位置付け、警告、または制限は保持してください。
- 3つ以上の項目の比較が散文に散らばっていますか？（はい → 表を使用すべき）
- 図はテキストよりもフローや状態を理解しやすくしますか？対象のレンダリング機能に応じてMermaidを選択するか、テキストを保持します。
- サンプルは、実際の疑問、エラー回復、または境界条件を解決していますか？対象読者にとって有効なサンプルを保持してください。
2. 修正（公理に従って適用）
具体的なルールは、以下の§公理 ① と §公理 ② を参照してください。
3. 検証（定量ベースライン）
修正後、必要に応じて チェックリスト を読み、情報の完全性と読みやすさを確認します。 すべての数値が達成される必要はありません。これらは診断ツールであり、法律ではありません。明確さを優先すべき場合は、例外を認めることができます。
公理 ①：素早く見つける
見出しの識別性
見出しは道標です。メンテナーが目次をスキャンしたときに、各セクションに何が含まれているか一目でわかるようにすべきです。
判断基準：セクションをクリックしないと何について書かれているかわからない場合、その見出しは曖昧すぎます。
| ❌ 曖昧 | ✅ 識別可能 | なぜ変更するか |
|---|---|---|
5.1 テーブルレベル | 5.1 プロジェクトCRUD（テーブルレベルエンドポイント） | 「テーブルレベル」は何でもありえます |
5.3 行レベル | 5.3 行レベルコラボレーションエンドポイント | 読者はここに割り当て/配信などの操作があるとわかります |
5.4 エクスポート | 5.4 全量CSVエクスポート | どの形式？全量か部分か？ |
エンドポイント | HTTPエンドポイント | 曖昧さを排除 |
テクニック：核となる概念が短すぎる場合は、括弧で限定詞を追加して重要な情報を補います。ただし、やりすぎないでください。 目標は、15文字以内で「このセクションに何があるか」を伝えることであり、論文のタイトルを書くことではありません。
情報アーキテクチャ
- 1セクション1責務：チュートリアル、操作、リファレンス、説明という主要な読者のタスクに基づいてコンテンツを整理します。必要なAPIシグネチャや簡単な背景情報は保持しても構いませんが、長文の資料はクロスリンクを使用します。
- 主要情報を先に、詳細は後に：最も重要な情報をセクションの先頭またはドキュメントの上部に配置します（プログレッシブディスクロージャー）。高度な情報やエッジケースは折りたたむか付録に配置します。
- 自己充足の原則：メンテナーがどのページから読み始めても、「前提知識」を必要としません（Every Page is Page One）。前置きとなる概念が必要な場合は、セクションの先頭で宣言し、リンクを提供します。
図表と代替テキスト
関係性、順序、比較を図で示す方が明確な場合にのみ図を使用します。検索可能なテキストと必要な代替説明は保持します。
決定木：
情報タイプは？
├─ マルチステップフロー / 分岐判断あり → フローチャート（flowchart）
├─ イベント駆動の状態変化 → 状態図（stateDiagram-v2）
├─ 3+ 項目 × 2+ 次元の比較 → テーブル
├─ コンポーネント関係 / アーキテクチャ階層 → 概略図 + 階層
├─ 定義 / コンテキスト / 正確な数値 → テキスト（デフォルト）
└─ 不明 → デフォルトテキスト（図は付加価値であり装飾ではない）
Mermaid ベストプラクティス：
- ノード数 ≤30 — それを超えるとレイアウトアルゴリズムが読めなくなるため、「概要→詳細」の複数図に分割
- 分岐条件や意味が不明瞭な関係にはラベルを追加。明確な順序矢印はラベル不要とし、ラベルノイズを避ける
subgraphを使用して関連ノードをグループ化TD（上から下）は階層に適しています。LR（左から右）はシーケンス/パイプラインに適しています。
テーブルデザイン（Tufte の原則）：
- 不要な線、網掛け、純粋な装飾を削除 — 「何よりもデータを表示せよ」
- 最小有効差異：視覚的な区別は可能な限り微妙でありながら、明確であること
- 数値は列で整列させ、スキャンと比較を容易にする
- テキストは常に水平方向に配置し、縦方向は禁止
公理 ②：各段落に用途がある
重複排除
同じ情報が複数の場所に現れることは、保守性の最大の敵です。一方を修正し、もう一方を忘れることになります。
検出基準（いずれかに該当 → 重複排除が必要）：
- 同じロジック/ルールが2つ以上のセクションに出現 → 権威あるソース（通常はデータモデルまたはステートマシンのセクション）を残し、残りは相互参照に変更
- 動作、前提条件、リスク、および独立した読解を確認した後、情報が失われないと確信できる段落 → 統合または削減
- ドキュメントが実装の詳細を重複して記述 → 読者に必要かどうかを判断。動作説明と契約は保持し、コードに既にあることを削除理由にしない
- 複数の同等な方法 → デフォルトの推奨事項を提示。互換性、権限、または使用条件が異なる必要な代替案は保持
ARID ≠ DRY：ドキュメントでは必要な繰り返しは許容されます。チュートリアルでリファレンスセクションの概念を再述することは合理的です。しかし、並行メンテナンスは排除します。同じ事実を2つの場所で独立して管理してはなりません。そうしないと、必ず一方が古くなります。
簡潔化
読者の現在のニーズに役立たないものはすべて削除します。
| 悪い兆候 | 修正方法 | 理由 |
|---|---|---|
| 繰り返しの前置き：「このセクションでは、…について説明します」 | 直接的な表現に統合 | 必要なステップの位置付けは保持 |
| 埋め草：「注意すべき点は」「特筆すべきは」 | 導入語を簡潔に | 警告または制限自体は保持する必要がある |
| 受動態の連発（「〜される」「〜されるだろう」） | 能動態SVOに変更 | より短く、明確で、読者は「誰が何をしているか」を理解できる |
| 同義語の濫用（同じ機能に異なる用語を使用） | 用語を統一し、1用語1意味に | 読者が同じ機能の名前を明確に理解できるようにする |
| 読みにくい長いネスト文 | 論理に従って文を分割 | 条件、例外、結論の関係を壊さない |
| 同等な方法の列挙 | 推奨方法を先に、必要な代替案は後に | 異なる制約下での実行可能な選択肢を保持 |
サンプルの抑制
サンプルは最も強力なクイックアンサーツールですが、最も悪用されやすいコンテンツタイプでもあります。 Write the Docs は意図的に「Include (some) examples」と書いています。括弧内の「some」は意図的な限定です。
サンプルを使用すべきタイミング:
- 読者が素早い答えを必要としており、サンプルに直接ジャンプする（多くの人の最初の反応）
- 具体例なしでは概念が理解しにくい
- 高頻度で実際のユースケースを示している
サンプルを使用すべきでないタイミング:
- 明らかなことを示している場合（Microsoft：「明白な点を説明しない」）
- 理解に役立たない人為的なシナリオ。明確にラベル付けされ、動作が検証可能な合成サンプルは保持できます。
- 単に「完全性」のために追加されており、ユーザーの実際のニーズに基づいていない
- サンプルが多すぎる — さらに追加するとスキャン性が低下する
良いサンプル:
- 最も一般的なユースケースのみをカバーし、網羅的ではない
- 自己完結型で実行可能（コピー＆ペーストで動作する）
- 単純なものから複雑なものへと段階的に進む
- 期待される出力を示して読者が検証できるようにする
- サンプルがまだ実行可能であるか、前提条件が明確にされている場合にのみ、定型コードを省略。必要なインポート、エラーハンドリング、期待される出力は保持する
悪いサンプル:
- 明らかなことを示している
- 非現実的な人工シナリオ
- 1つのサンプルで多すぎる変数をカバーしようとしている
- サンプルに関係のない例外処理を詰め込んでいる
- 検証されていないのに実行可能と主張するコード。実行できない場合は、検証の制限を明確に注記する
配置ルール:
- 単純な1行サンプル → 本文中にインライン
- 長めのサンプル → 密集したリファレンス資料から分離（独立した段落または折りたたみ領域）
- リファレンスドキュメント内のサンプル → 抑制を保ち、使用法の説明のみを目的とし、チュートリアルを混在させない
定量ベースラインクイックリファレンス
以下は、言語と読者に応じて調整された初期スクリーニングのためのヒントです。詳細は チェックリスト を参照してください。
| 次元 | 推奨開始点 | 使用上の境界 |
|---|---|---|
| 英文の文長 | 約20語以降でネストに注意 | 日本語に機械的に適用せず、条件や契約を壊さない |
| 段落 | 1段落1主要ポイント | 例外と警告は元の段落に続けて配置可能 |
| リスト/ステップ | 長い場合はグループ化を検討 | 項目数を揃えるために完全なステップを削除しない |
| 受動態 | 主体が不明確な場合に書き換え | 達成すべき割合を設定しない |
| Mermaid | ノードが多い場合は概要と詳細を検討 | 実際のレンダリングの可読性で判断 |
| テーブル | 幅の広いテーブルは分割または転置を検討 | 比較に必要な列と単位は保持 |
数値は推奨であり、業界の合格基準や研究上の法則ではありません。事実、契約、安全性、または法的なテキストを変更するために数値を達成する必要はありません。
アンチパターンクイックリファレンス
| アンチパターン | 症状 | 解決策 |
|---|---|---|
| Almighty Thud | 巨大なドキュメントですべての情報が等しく扱われ、重要な決定が埋もれる | 分割するか、優先度の階層を追加 |
| タイプ混在 | チュートリアルにAPIリファレンスを詰め込み、リファレンスに「なぜ」を書く | Diátaxisに従って分割 |
| 繰り返しの前置き | 実質的な情報のない導入文 | 表現を簡潔にし、リスクとステップ情報は保持 |
| 同義語の濫用 | 同じ機能に異なる用語を使用 | 用語を統一 |
| 関係の不明瞭さ | 分岐や矢印の意味を推測する必要がある | 不明瞭な関係にラベルを追加 |
| chartjunk | テーブルに不要な装飾線や網掛けを追加 | 情報を伝えない装飾を削除 |
| サンプル過多 | すべてのシナリオを網羅するサンプル | 最も一般的なユースケースのみを残す |
| 並行メンテナンス | 同じ事実が複数の場所で独立して管理されている | 1箇所に残し、残りはリンクに変更 |