Diátaxis
Diátaxis はテクニカルドキュメントの体系的アプローチで、Daniele Procida（Canonical）によって 2017 年頃に formalize されました。現在 Django、Cloudflare、GitLab、NumPy、Gatsby ほか数十の主要 OSS プロジェクトで採用されています。
名前はギリシャ語の diá（「横断」）+ táxis（「配置」） ― 4 つの軸に渡る意図的な順序付け。
| 正本リンク | https://diataxis.fr |
|---|---|
| 著者 | Daniele Procida |
| キット内の home | template/docs/user-manual/ |
| pentaglyph 内のスロット | 5 つ中 #4 ― ユーザー向け docs 層 |
Diátaxis は何を解決するのか
Section titled “Diátaxis は何を解決するのか”ほとんどのテクニカル doc は次の 2 失敗モードに陥ります:
- 単一「docs」山 ― チュートリアル・リファレンス・解説・how-to が交ざる。読者は何も見つけられない
- 2 バケット分割（例: 「Getting Started」+ 「API Reference」） ― 学びながら作る（チュートリアル）と 既知問題の解決（how-to）、 理解する（説明）と 調べる（リファレンス）を区別できない
Diátaxis は 読者ニーズには厳密に 4 種類 があり、1 つの doc に 2 つを混ぜるとどちらも務まらないと観察します。
| 実践的ステップ | 理論的知識 | |
|---|---|---|
| 学習指向 | Tutorials | Explanation |
| 作業指向 | How-to guides | Reference |
Tutorials ― 学びながら作る
Section titled “Tutorials ― 学びながら作る”読者は 初めての学習者。著者が彼らの手を引いて保証された成功へ導く。トレードオフを隠す。代替案を隠す。目標は 初の成功体験 であって理解ではない。
How-to guides ― 問題を解決する
Section titled “How-to guides ― 問題を解決する”読者は 既に何をしたいか分かっている ので recipe が必要。既知ゴールへの具体ステップ。決定関連ならトレードオフが出現する場合あり。
例: ADR の書き方
Reference ― 調べる
Section titled “Reference ― 調べる”読者は 正確な事実が必要。dry で完全、機械のような記述。ナラティブなし、手を引かない。最も長く最も読まれない内容になりがちだが必要なときには不可欠。
例: テンプレート目録
Explanation ― なぜを理解する
Section titled “Explanation ― なぜを理解する”読者は 既にシステムを使っており、なぜこの形をしているかを理解したい。論述的、opinionated、理論的。「エッセイ」象限。
doc が 2 象限にまたがるなら、分割する
リファレンスを兼ねようとしたチュートリアルは誰も読まない caveats の壁になる。説明を兼ねようとした how-to は誰も読み終えない digression になる。4 象限分離こそが価値命題全体であって、ゆるめると枠組み自体が無効になる。
pentaglyph での Diátaxis の使い方
Section titled “pentaglyph での Diátaxis の使い方”template/docs/user-manual/├── tutorials/ ← 初成功 walkthrough├── how-to/ ← 既知問題のレシピ├── reference/ ← 正確な事実、dry└── explanation/ ← 論述的な「なぜ」コンテンツこのリポには 2 つの異なる
docs/がある。docs/（pentaglyph 自身の ユーザーマニュアル）とtemplate/docs/user-manual/（pentaglyph initで プロジェクトに copy される もの）。混同しないこと。
あなたが今読んでいるこのサイト そのもの が pentaglyph 用 Diátaxis 編成マニュアルです。sidebar は 4 象限に直接マップ（+ 初回 orientation の「Start」 + このリファレンスページの「Standards」）。
Diátaxis を使うべきとき
Section titled “Diátaxis を使うべきとき”- ユーザー向け docs を出荷する任意のプロジェクト（開発者ツール、ライブラリ、SaaS）
- 複数著者が contribute する場合に特に有用 ―― 象限が ad-hoc 構造ドリフトを防ぐ
Diátaxis を使う べきでない とき
Section titled “Diátaxis を使う べきでない とき”- 純粋な内部アーキテクチャ docs（arc42 を使う）
- 単一ページ README ―― オーバーヘッドが価値を超える
- 公式サイト: https://diataxis.fr（短いので最初に読む）
- 著者の home page: https://evildmp.org（Daniele Procida）
- トーク: What nobody tells you about documentation ― Daniele Procida at PyCon US
- 採用例: Django docs、Cloudflare Workers docs、GitLab handbook、NumPy
- なぜ pentaglyph が存在するのか ― Diátaxis 単独では足りない理由
- テンプレート目録 ― pentaglyph のテンプレート 0-13
- arc42 ― pentaglyph が Diátaxis と組み合わせるアーキテクチャ側の counterpart