Diátaxisとは
Diátaxisとはテクニカルドキュメントの構造化フレームワークです。
ユーザーのニーズの体系的な説明と分析に基づいて文書構造を規定するスキームを提供し、多くのソフトウェアのテクニカルドキュメントの体系として採用されています。
Diátaxis という名前は、古代ギリシャ語の dia (横切る)と、taxis(整理・配置) に由来するそうです。
- ドキュメンテーションを 2 つの知識軸 (理論/実践、および習得/応用) に分割して整理
- TutorialsとHow-to guidesの両方で、実践的な手順を説明
- How-to guidesとReferenceは知識の応用に関係
- Reference と Explanation に理論的知識が含まれる
- Tutorials と Explanation は知識の習得に関係
Tutorials
チュートリアルは、ある種のプロジェクトを完了するための一連のステップを通して読者を手で指導するレッスン
| 項目 | 説明 |
|---|---|
| 何をする | 紹介する, 教育する, 導く |
| どのような質問に答えるものか | 「教えてれますか？」 |
| 指向 | 学習指向 |
| 目的 | 新人が開始できるようにする |
| 形式 | レッスン |
| アナロジー | 子供に料理を教える |
How-to guides
ハウツー ガイドは、実際の問題を解決するために必要な手順を読者に案内する指示
| 項目 | 説明 |
|---|---|
| 何をする | ガイドする、デモする |
| どのような質問に答えるものか | 「どのようにすればいいですか？」 |
| 指向 | 目的(タスク)指向 |
| 目的 | 特定の問題を解決する方法を示す |
| 形式 | 一連の手順 |
| アナロジー | 料理本のレシピ |
Reference
リファレンス ガイドは、機械とその操作方法の技術的な説明
| 項目 | 説明 |
|---|---|
| 何をする | 述べる、記述する |
| どのような質問に答えるものか | 「・・とは何ですか？」 |
| 指向 | 情報指向 |
| 目的 | 機構についての記述 |
| 形式 | 淡々とした記述 |
| アナロジー | Wikipediaの記事 |
Explanation
説明は、特定のトピックを明確にし、明らかにする議論
| 項目 | 説明 |
|---|---|
| 何をする | 説明する、明らかにする、議論する |
| どのような質問に答えるものか | 「なぜ、どうして？」 |
| 指向 | 理解指向 |
| 目的 | 説明する |
| 形式 | 言説的な説明 |
| アナロジー | 料理社会史の記事 |
