diataxis

Diátaxis

Diátaxis フレームワークを使って技術ドキュメントを作成・修正するためのランブックです。Diátaxis では、ドキュメントを チュートリアル、ハウツーガイド、リファレンス、解説 の4つのモードに分けます。それぞれが、相反する方向に引っ張り合う、異なる4つのユーザーニーズに応えるためです。機能させるための核となる考え方は、次のとおりです。

ドキュメントの問題のほとんどは、ひとつのことに集約されます。複数のニーズに同時に応えようとしているコンテンツです。4つのモードを分ければ、たいていの混乱は解消されます。

Diátaxis は規範的なものではなく、記述的なものです。ドキュメントを埋めるテンプレートではなく、ドキュメントを 理解する ための方法です。フレームワーク全体を理解するまで適用を待つ必要はありません。小さなものをひとつ選び、分類して、改善し、公開し、繰り返してください。

適用する場面

次のような場合に、このスキルを使ってください。

• README、API ドキュメント、ガイド、オンボーディング資料、開発者向けドキュメントなど、あらゆる種類の新しいドキュメントを作成または生成する場合。執筆を始める 前に、コンテンツに必要なモードを決めてください。
• ページが わかりにくい、肥大化している、または「あれもこれも詰め込もうとしている」 場合。モードの混在を診断し、分割してください。
• ユーザーが使い始められない、タスクを完了できない、事実を見つけられない、または なぜ なのかを理解できない 場合。欠けている、または弱いモードを特定してください。
• 既存のドキュメント群を 再構成または監査する 場合。大規模な書き直しではなく、小さなステップで進めるワークフローを適用してください。
• ある内容がチュートリアル、ハウツーガイド、リファレンス、解説のどれに当たるか判断できない 場合。コンパスを使ってください。

適切なモードがすでに決まっているドキュメント内の文章を純粋に推敲する場合（コピーライティング用スキルを使ってください）や、設計・仕様・提案書には、このスキルを使わないでください。そうした文書は主に 解説 に当たり、dev-rfc または feature-spec のほうが適しています。

4つのモード

それぞれのモードは、異なる状況にいる異なるユーザーに向けて、異なるスタイルのコンテンツを提供します。違いを把握するための最も簡単な方法は次のとおりです。

モード	対象	主眼	たとえ	答える質問
チュートリアル	学習中 の初心者	学習、勉強	子どもに料理を教える	「実際にやりながら教えて」
ハウツーガイド	作業中 のユーザー	目標、タスク	料理本のレシピ	「X を達成するにはどうすればいい？」
リファレンス	作業中 のユーザー	情報	百科事典の項目	「X とは正確には何？」
解説	学習中 のユーザー	理解	料理についての解説記事	「X はなぜこのようになっている？」

2つのモードは 実践的な手順 を提供します（チュートリアル、ハウツー）。残りの2つは 理論的な知識 を提供します（リファレンス、解説）。2つのモードは スキルを身につける／学ぶ 人向けです（チュートリアル、解説）。残りの2つは スキルを応用する／作業する 人向けです（ハウツー、リファレンス）。

コンパス — 何を書くかを決める

コンテンツがどのモードに当てはまるか判断できない場合は、2つの質問に答えてください。これは判断のための基本ツールです。詳細なツリーは compass-tree.md にあります。

1. 行動 に情報を与えるものですか、それとも 認識 に情報を与えるものですか？ — 実践的な手順（実行する）か、理論的な知識（考える）か。 2. 習得 を支援するものですか、それとも 応用 を支援するものですか？ — 学習（学ぶ）か、作業（知っていることを応用する）か。

	行動（実践的な手順）	認識（理論的な知識）
習得（学習）	チュートリアル	解説
応用（作業／実行）	ハウツーガイド	リファレンス

判断方法として読むと、次のとおりです。行動に情報を与える + 習得を支援する → チュートリアル。行動に情報を与える + 応用を支援する → ハウツーガイド。認識に情報を与える + 応用を支援する → リファレンス。認識に情報を与える + 習得を支援する → 解説。 コンパスは、文書全体、セクション、または誤ったモードにずれてしまった一文など、どの規模にも適用できます。

よくある症状

まずここから始めます。状況に合うものを見つけて、そのツリーを開いてください。深刻度は、読者が現時点でどれほど困っているかを示します（symptoms.mdを参照）。

症状／きっかけ	考えられる問題	ツリー
「Xのドキュメントを書いて」／「これを文書化して」――どんな種類のドキュメントにすべきか不明	モードがまだ選ばれていません。まず分類します	compass-tree
ページが冗長でまとまりがない、あるいは解説＋手順＋仕様＋意見が混在している	種類の混在――1つのドキュメントで2つのニーズに応えています	wrong-type-tree
初心者が始められない・慣れたユーザーがタスクを完了できない・事実を見つけられない・ユーザーが「なぜ」を理解できない	いずれかの領域が欠けている、または不十分です	gaps-tree
「ドキュメントが散らかり放題です。どこから手をつければいいのでしょうか？」	書き直しではなく、反復的なワークフローが必要です	restructure-tree

使い方

1. 上の表で症状を照合し、references/にある該当のツリーを開きます。大規模な既存のドキュメント群の場合は、まず bash references/queries/scan-docs.sh <docs_root> を実行してください。複数のモードの兆候が見られるページをトリアージできるため、どこにコンパスを適用すべきかがわかります。
2. コンパスを使って分類します。コンテンツが4つのモードのどれに当たるかを判断してください。迷ったときは、compass-tree.mdを開いてください。
3. 該当する種類のガイドを読みます。チュートリアル、ハウツーガイド、リファレンス、解説を読み、そのモードに適した書き方と、含めるべきでない内容を確認してください。
4. 小さなステップで進めます。workflow.mdに従い、小さな対象を選ぶ → 評価する → 次のアクションを1つ決める → 実行して公開する、という順に進めます。すべてを壊して上から再構成することは決してしないでください。
5. 品質に照らして評価します。quality.mdを使い、機能的な品質（正確性、網羅性、一貫性）と深い品質（使いやすさ、ユーザーのニーズを先回りして捉えているか）を判断してください。
6. 既存のドキュメント一式をレビューする際は、assets/templates/report.mdを使って監査結果を記録し、同じ不足点が毎回議論し直されることを防ぎます。

セットアップ

このスキルでは、ドキュメントの保存場所と監査結果の記録先を把握するため、任意の config.json を使用します。初回使用時に docs_root が空で、既存のドキュメント一式を監査する場合は、ユーザーに AskUserQuestion 経由でドキュメントディレクトリを尋ねて保存してください。設定がなくてもスキルは動作します。その場合は、その場で質問してください。設定がないことを理由に処理を止めないでください。

注意点

Diátaxisを適用する際に繰り返し起こりがちな落とし穴――構造を先に作るだけの空の枠組み、「4種類のバランスを取る」ことを重視して分離しないこと、チュートリアルの中で解説すること――については、gotchas.mdに記載されています。初めて再構成する前に読んでください。

関連スキル

• skill-authoring — Agent Skillsの作成。各スキルのSKILL.md自体がDiátaxisの課題です（チュートリアルではなく、ナビゲーション＋リファレンス）。
• human-copywrite / humanize — ドキュメントを適切なモードに分類した後、文章を整えて自然に読めるようにします。
• dev-rfc / feature-spec — 設計文書と仕様書は主に解説です。成果物がユーザー向けドキュメントではなく提案である場合に活用してください。