diataxis

Diátaxis ドキュメントフレームワーク

Diátaxis の体系的なフレームワークを適用して、ドキュメントを構成し、執筆します。

4 種類のドキュメント

Diátaxis では、2 つの軸によって定義される 4 種類のドキュメントを特定します。

	習得（学ぶ）	適用（作業する）
行動（実践する）	チュートリアル	ハウツーガイド
認知（考える）	解説	リファレンス

1. チュートリアル — 学習指向

チュートリアルはレッスンとして書きます。実践的な体験を通して、学習者が実際に手を動かしながらスキルを身につけられるよう、手を引いて導きます。

• 一人称複数形（「一緒に〜しましょう」）を使います
• 最初に、どこへ向かうのかを示します
• 早い段階から、目に見える成果を繰り返し提示します
• 説明は徹底的に最小限にし、代わりにリンクを張ります
• 具体的な内容に集中し、オプションや代替手段は扱いません
• 確実に機能することを目指します

詳しい指針については references/tutorials.md を読み込んでください。

2. ハウツーガイド — 目標指向

ハウツーガイドは、すでに十分な知識を持つユーザーが、具体的な実務上の目標を達成するための実践的な手順として書きます。

• 「［X を達成する方法］」のように、内容が明確に分かる名前を付けます
• 条件付きの命令形（「x をしたい場合は、y をしてください」）を使います
• ユーザーには十分な知識があると想定し、教え込もうとしません
• 不要な内容は省きます。網羅性よりも実用性を重視します
• 代替手段を示し、柔軟に対応できるようにします

詳しい指針については references/how-to-guides.md を読み込んでください。

3. リファレンス — 情報指向

リファレンスは、仕組みを技術的に記述したものとして書きます。簡潔で権威ある内容にし、通読ではなく、必要なときに参照するものとします。

• 記述に徹します。中立的な調子で、説明だけを行います
• 標準的で一貫性のあるパターンを採用します
• 製品の構造を反映します
• 説明のためではなく、例示のために例を示します

詳しい指針については references/reference.md を読み込んでください。

4. 解説 — 理解指向

解説は、理解を深めるための詳しい論述として書きます。「〜について教えてもらえますか？」に答える内容です。

• 関連するトピックとのつながりを示します
• 背景を説明し、なぜそうなっているのかを伝えます
• 主題について語ります（タイトルは「X について」）
• 意見や視点を明らかにします
• 範囲を狭く保ち、ほかの種類の内容を取り込まないようにします

詳しい指針については references/explanation.md を読み込んでください。

コンパス — 判断に迷ったとき

次の 2 つの問いを使って、内容を分類します。

1. 行動か認知か？ 実践することについてですか、それとも考えることについてですか？
2. 習得か適用か？ 学ぶためのものですか、それとも作業するためのものですか？

2 つの軸の交点から、書くべき種類が分かります。詳しい判断指針については references/compass.md を読み込んでください。

適用方法

1. 内容を分類します。上記のコンパスの問いを使います。
2. 種類が混在していないか確認します。一度に 2 つのことを扱おうとしていませんか？
3. 混在した内容を分けます。チュートリアルから解説を切り離し、リファレンスから手順を切り離します。
4. その種類の原則を適用します。上記の箇条書きに従います。
5. 種類同士をリンクします。内容を埋め込まず、相互参照を使います。

空の 4 セクション構成を作って、内容を埋めようとしてはいけません。内容から自然に構成を導き出します。

例

ユーザーからの依頼：「CLI ツールの入門ガイドを書いてください。」

1. 分類：「入門」は、ユーザーが実践しながら学ぶことを意味します → チュートリアル。
2. 確認：これはハウツーガイドではありません。ユーザーは具体的な問題を解決するのではなく、ツールに慣れるための知識を身につけようとしています。
3. チュートリアルの原則を適用：
   • 何を作るのかを冒頭で示します。「このチュートリアルでは、CLI をインストールしてサンプルアプリをデプロイします。」
   • 各段階で目に見える成果を示しながら、具体的な手順を案内します。
   • 説明は最小限にします。「出力を増やすには --verbose を使います」とし、ログレベルについて段落を割いて説明することはしません。
   • フラグの詳細はリファレンスに、アーキテクチャについては解説にリンクします。
4. 結果：機能を紹介するだけのチュートリアルではなく、焦点を絞ったレッスンになります。

よくある間違い

間違い	うまくいかない理由	修正方法
すべてを説明するチュートリアル	説明によって学習の流れが途切れ、学習者の集中力が失われます	説明は別のドキュメントに移し、リンクします
基礎を教えるハウツーガイド	十分な知識を持つユーザーにオンボーディングは不要で、時間を無駄にします	ユーザーが十分な知識を持っていることを前提にするか、チュートリアルとハウツーガイドに分けます
意見やアドバイスを含むリファレンス	リファレンスを参照するユーザーが必要としているのは事実であり、ガイダンスではありません	アドバイスは解説に移します
リファレンスに解説を混在させる	どちらの質も下がります。リファレンスは冗長になり、解説は掘り下げられなくなります	個別のドキュメントに分けます
実際には機能紹介になっている「はじめに」	学習目標も一貫した道筋もなく、ユーザーはスキルを身につけられません	ユーザーが達成することを1つ選び、それに向けて構成します
空のチュートリアル／ハウツーガイド／リファレンス／解説セクションを作成する	内容のない構成は役に立たない足場にすぎません	まず内容を書き、構成はそこから形作ります

重要なルール

• 種類を混在させないでください。 それぞれの種類には、独自の目的、トーン、形式があります。
• ユーザーのモードが重要です。 学習と作業の違いが、根本的な区分です。チュートリアルと解説は学習を支援し、ハウツーガイドとリファレンスは作業を支援します。
• ある種類を別の種類に埋め込むのではなく、種類の間にリンクを張ってください。

詳細な解説

詳しいガイダンスが必要な場合は、必要に応じてリファレンスファイルを参照してください。

トピック	ファイル
チュートリアルの作成	references/tutorials.md
ハウツーガイドの作成	references/how-to-guides.md
リファレンスドキュメントの作成	references/reference.md
解説の作成	references/explanation.md
コンパス判断ツール	references/compass.md
チュートリアルとハウツーの違い	references/tutorials-how-to.md
リファレンスと解説の違い	references/reference-explanation.md
ワークフローの方法論	references/how-to-use-diataxis.md
Diátaxisが機能する理由（基礎）	references/foundations.md
2次元マップ	references/map.md
ドキュメントの品質	references/quality.md
複雑な階層構造	references/complex-hierarchies.md