writing-documentation-with-diataxis

Diataxis を使ったドキュメントの作成

Diataxis フレームワークを使って、ユーザーが技術ドキュメントを作成・改善できるよう支援します。このフレームワークでは、ユーザーのニーズに基づいて、ドキュメントを4つの異なる種類に分類します。

Diataxis とは

Diataxis は、使い心地のよいドキュメントを作成するためのフレームワークです。流れがあり、ニーズを先回りして、実際に人が技術に取り組む方法に合ったドキュメントを目指します。

重要：Diataxis はアプローチであり、テンプレートではありません。チュートリアル、ハウツー、リファレンス、解説の各セクションを設けるためだけに、空のセクションを作成しないでください。実際のユーザーニーズに応えるコンテンツを作成し、これらの原則を適用すれば、構成は自然に生まれます。

中心となる考え方：ドキュメントは、ある分野のスキルを実践する人々のためのものです。必要なものは、次の2つの軸によって変わります。

1. 行動と認知 — 何かをすることと、理解すること
2. 習得と実践 — 学ぶことと、作業すること

この2つの軸から、ドキュメントの種類はちょうど4つに定まります。

• 実践しながら学ぶ → チュートリアル
• 目標を達成するために作業する → ハウツーガイド
• 作業中に事実を確認する → リファレンス
• 理解するために学ぶ → 解説

ちょうど4つである理由：これらは恣意的な分類ではありません。2つの軸によって、領域はちょうど4つに分かれます。3つや5つにはなりません。これは、ドキュメントが網羅すべき領域の全体です。

Diataxis の羅針盤（主なツール）

どの種類のドキュメントが必要か迷ったら、次の2つの質問をしてください。

1. コンテンツは行動に役立ちますか、それとも認知に役立ちますか？

• 行動：実践的な手順、何かを行うこと
• 認知：理論的な知識、理解すること

2. スキルの習得に役立ちますか、それとも実践に役立ちますか？

• 習得：学習、勉強
• 実践：作業、物事を成し遂げること

次の表に当てはめます。

コンテンツの種類	ユーザーの活動	ドキュメントの種類
行動	習得	チュートリアル
行動	実践	ハウツーガイド
認知	実践	リファレンス
認知	習得	解説

新しいドキュメントを作成する場合

1. ユーザーのニーズを特定する

次のことを自問してください。

• ユーザーは誰ですか？（学習者、それとも実践者）
• 何を必要としていますか？（何かをすること、それとも何かを理解すること）
• どのような状況ですか？（学習中、それとも作業中）

2. 羅針盤を使う

上記の2つの質問を使い、そのニーズに合ったドキュメントの種類を判断してください。

3. コア原則を適用する

チュートリアル（実際に手を動かして学ぶ場合）：

• 学習者が成功できるようにする責任があります。すべての手順が機能しなければなりません
• 説明ではなく、実際に行うことに重点を置きます
• 何を目指すのかを最初に示します
• 目に見える成果を早い段階から頻繁に提示します
• 「次のようになります」「ここに注目してください」など、期待を示す流れを保ちます
• 具体的かつ明確にします。選択肢は設けず、手順は一つに絞ります
• 予想外のことが起きないようにします。完全に再現可能な内容にします
• 「実際に行う感覚」を身につけられるよう、繰り返しを促します
• 完全な信頼性を目指します

ハウツーガイド（目標を達成するために作業する場合）：

• ツールの機能ではなく、現実の問題を扱います
• 読者の能力を信頼します。読者は自分の望むことを理解しています
• 人の考え方に沿って、論理的な手順を提示します
• 条件分岐（「X の場合は Y を実行します」）を使って、現実の複雑さに対応します
• 作業の流れを重視します。次の行動を先読みし、コンテキストの切り替えを最小限に抑えます
• 不要な詳細は省きます。完全性より実用性を優先します
• ツールではなくタスクに焦点を当てます
• ガイドには明確な名前を付けます：「[X を達成する方法]」

リファレンス（作業中に事実を確認する場合）：

• 指示ではなく説明を記載し、中立的な事実だけを示します
• 構成は製品のアーキテクチャを反映します
• 全体を通じて標準的で一貫したパターンを使用します
• 簡潔で権威ある内容とし、曖昧さをなくします
• 説明と指示を分けます
• 簡潔な使用例を提示します
• ここでは完全性が重要です（ハウツーガイドとは異なります）

解説（概念を理解する場合）：

• 複数の視点から対象について説明します
• 設計上の判断、歴史、制約を取り上げ、「なぜ」に答えます
• 関連する概念とのつながりを示します
• 背景や全体像を提示します
• 意見や見解を述べてもかまいません。トレードオフについても議論します
• 境界を明確に保ちます。指示や純粋なリファレンスにはしません
• より高く、広い視点から捉えます

4. 適切な言葉遣いを使う

チュートリアル：「これから作成します」「まず、X を実行します。次に、Y を実行します」「ここに注目してください」「これで構築できました」

ハウツーガイド：「このガイドでは、～する方法を説明します」「X を行う場合は、Y を実行します」「W を達成するには、Z を実行します」

リファレンス：「X は Y として利用できます」「サブコマンドは A、B、C です」「X を使用する必要があります。Y は決して使用しないでください」

解説：「X の理由は～です」「W が Z より優れているのは、～だからです」「W を好む人もいます。これは効果的な場合がありますが、～」

5. 境界を確認する

内容を見直します：

• ある部分が、別のユーザーニーズに応えていませんか？
• チュートリアルに解説が含まれていませんか？（切り分けてリンクします）
• リファレンスで指示をしていませんか？（ハウツーガイドに移します）
• ハウツーガイドにリファレンスの詳細が含まれていませんか？（代わりにリファレンスへリンクします）

内容が複数のニーズに応える場合は、分割して文書間を相互にリンクします。

既存のドキュメントをレビューする場合

次の反復的なワークフローを使用します：

1. 対象を選ぶ — ページ、セクション、段落のいずれでもかまいません

2. 次の質問で検討する：

• どのユーザーニーズに応える内容ですか？
• どのドキュメントタイプにするべきですか？
• そのニーズに適切に応えていますか？
• このタイプに適した言葉遣いですか？
• 別のタイプに属する内容はありませんか？

3. タイプが明確でない場合は、羅針盤を使う

4. 今すぐ役立つ改善点を一つ見つける

5. Diataxis の原則に従って改善する

6. 別の箇所で繰り返す

すべてを一度に再構成しようとしないでください。個々の箇所を改善していくことで、構成が形作られます。

主要原則

フローが最優先です：ドキュメントはユーザーの次のニーズを予測しながら、スムーズに読み進められるようにします。特にハウツーガイドでは、次の点を考えてください。ユーザーは何を覚えておく必要があるでしょうか？そうした疑問をいつ解決できるでしょうか？次に何を必要とするでしょうか？

境界はユーザーを守ります：ドキュメントの種類を分けてください。最もよくある間違いは、チュートリアル（学習）とハウツーガイド（作業）を混同することです。

構成は内容に沿って決めます：空のセクションは作らないでください。実際のニーズに応える内容を書き、Diataxis の原則を適用し、構成が自然に形づくられるようにします。

一度に一つのニーズに応えます：それぞれのドキュメントは、ユーザーのニーズを一つ満たします。複数のニーズがある場合は、ドキュメントを複数作成し、相互にリンクしてください。

優れたドキュメントは読み心地のよいものです：正確であるだけでなく、ニーズを先読みし、流れがあり、人の作業の仕方に合ったドキュメントを目指してください。

避けるべきよくある間違い

1. チュートリアルとハウツーの混同 - チュートリアルは学習のためのもの、ハウツーガイドは作業のためのものです。混同している兆候は次のとおりです。

   • 「チュートリアル」で、ユーザーが何をしたいかをすでに知っていることを前提としている
   • 「チュートリアル」で複数の方法を提示している
   • 「ハウツーガイド」で基本概念を教えようとしている
   • 「チュートリアル」で実際の複雑な状況を扱っている

2. チュートリアルでの過剰な説明 - 実践を通じて学べることを信頼してください。説明は最小限にし、詳しい説明には別の場所でリンクしてください。

3. 教えようとするハウツーガイド - ユーザーには十分な知識があることを前提にしてください。基本は説明しないでください。

4. 手順を指示するリファレンス - リファレンスは内容を記述するものであり、何をすべきかを指示するものではありません。

5. 行動指向のドキュメントでの解説 - 解説は解説ドキュメントに移し、そこにリンクしてください。

クイックリファレンステーブル

項目	チュートリアル	ハウツーガイド	リファレンス	解説
答える質問	「教えてもらえますか？」	「どうすれば……？」	「……とは何ですか？」	「なぜ……？」
ユーザーの状態	実践しながら学んでいる	作業に取り組んでいる	作業中で、事実を必要としている	理解するために学んでいる
内容	アクション手順	アクション手順	情報	情報
形式	レッスン	手順	説明	論考
責任の所在	教える側	ユーザー	中立	共有
トーン	親しみやすく、導くような	直接的で、条件を明示する	簡潔で、事実に基づく	論述的で、文脈を踏まえた

補足ファイル

詳しい指針については、次を参照してください。

• principles.md - 各ドキュメントタイプの包括的な原則と例
• reference.md - 品質フレームワーク、複雑なシナリオ、その他の指針

出力要件

Diataxis を適用する際は、次の点に従ってください。

• 直接的かつ実用的にしてください
• ユーザーのニーズを満たすことに焦点を当ててください
• 不確実な点を解決するためにコンパスを使ってください
• 適用するドキュメントタイプとその理由を明記してください
• ドキュメントをレビューする場合は、どのタイプにすべきか、どう改善すべきかを具体的に示してください
• 全体を通してイギリス英語の綴りを使用してください