1. 導入：なぜドキュメントは読まれないのか
開発現場において「ドキュメントを書いたのに誰も読んでくれない」「必要な情報がどこにあるか分からない」という悩みは尽きません。この原因の多くは、チュートリアルとAPIリファレンスが混在するなど、ドキュメントの「目的」が整理されていないことにあります。Diataxisフレームワークは、ドキュメントを4つの構成要素に分類することで、読者が「今求めている情報」に最短距離で到達できる状態を作るための設計思想です。これを導入することで、開発チームのオンボーディング負荷を劇的に下げ、サポートコストを削減できます。
2. 基礎知識：Diataxisの4つの分類
Diataxisでは、以下の4つの軸で情報を切り分けます。
・Tutorials（学習）：初心者が手を動かし、成功体験を得るための「道案内」。
・How-to guides（作業）：特定の目的を達成するための「手順書」。
・Explanation（理解）：なぜその技術を使うのか、背景や概念を解説する「読み物」。
・Reference（仕様）：API仕様や設定パラメータなど、事実を羅列した「辞書」。
これらは「学習者向けか、実務者向けか」「抽象的か、具体的か」というマトリクスに基づいています。
3. 実装/解決策：ドキュメント構造の再設計
既存のドキュメントを整理する際は、まず「このページは誰のどんな欲求を満たすためのものか？」を問い直してください。例えば、「APIの全パラメータ一覧」と「APIを使った認証の実装手順」を同じページに書くのはNGです。前者は「Reference」に、後者は「How-to guides」に分離し、相互にリンクを貼るのが正解です。
4. サンプルプログラム：ドキュメント構造のテンプレート例
以下は、READMEやドキュメントサイトの構成案を示すディレクトリ構造の例です。各ディレクトリに目的を特化させることで、メンテナンス性が向上します。
ドキュメントディレクトリ構成の例
docs/
├── tutorials/ # 初心者向け：ゼロから環境構築までをステップバイステップで記述
│ └── get-started.md
├── how-to/ # 現場向け：具体的な操作手順（例：DBのマイグレーション手順）
│ └── migrate-db.md
├── explanation/ # 設計思想：なぜこのアーキテクチャを採用したかの背景
│ └── architecture.md
└── reference/ # 仕様：引数や型定義（自動生成推奨）
└── api-spec.md
5. 応用・注意点：現場での運用コツ
Diataxisを適用する際、最も陥りやすい罠は「全ての項目を埋めようとすること」です。特にReferenceは、SwaggerやTypeDocなどのツールでコードから自動生成し、人間がメンテナンスする工数を最小化しましょう。逆に、How-to guidesは最も更新頻度が高く、かつ読まれる場所です。ここには「トラブルシューティング」へのリンクを必ず含め、読者が迷子にならないような導線を設計してください。ドキュメントは「書くこと」がゴールではなく、「読者が目的を達成すること」がゴールであることを忘れないようにしましょう。
コメント