Diátaxis：書くこと、整理すること、届けること
「シンプルであることは、複雑であることよりも難しい。」
これはアップルの創業者スティーブ・ジョブズの言葉です。
技術の世界では、わかりやすい説明ほど、作り手の深い理解と整理の手間が詰まっているもの。
さて、いま海外のエンジニアたちの間で、技術文書をシンプルかつ的確に整えるためのフレームワークとして「Diátaxis」が話題を呼んでいます。
Diátaxis（ディアタクシス）は、古代ギリシャ語で「横断的な配置」を意味し、ドキュメントを利用者の目的に応じて四つのタイプに分類する考え方です。
提唱者であるダニエル・プロキダ氏は、ドキュメントの読者が抱くニーズを「チュートリアル」「ハウツーガイド」「リファレンス」「説明」の四つに分け、それぞれに適した書き方と構造があると説きます。
四つの象限、ドキュメントの羅針盤
Diátaxisの核は、四つのドキュメント形式をコンパス（羅針盤）になぞらえたフレームワークです。
- チュートリアル：初心者を手取り足取り導く「学習」のための文書。順を追って全体像を掴んでもらい、成功体験を積ませることを重視します。
- ハウツーガイド：特定の課題を解決する実践的な手順を示します。「〇〇をしたい」という目的を持った読者に、最短の道筋を提供します。
- リファレンス：事実や仕様を淡々と記述する情報の集積。APIのパラメータ一覧や設定値など、正確さと網羅性が求められます。
- 説明：背景や設計思想、技術選定の理由など、深い理解を促すための文章。読み物としての魅力も求められる、少し趣の異なる形式です。
これらは単なる分類ではなく、互いに関係し合いながらドキュメント全体を構成します。
チュートリアルで動かし方を覚え、ハウツーで実践し、リファレンスで詳細を調べ、説明で納得する、という流れが自然に生まれるのです。
なぜ四つに分けるのか、ユーザーが求める地図
技術文書の多くが抱える問題は、「これがチュートリアルなのか、リファレンスなのかわからない」といった混在です。
読み手は自分が欲しい情報を探すのに迷い、書き手も何を基準に書けばいいか悩みます。
Diátaxisは、それぞれの文書の目的を明確にすることで、書き手に「いま、この読者は何を求めているか」を意識させます。
たとえば、APIのドキュメントを書くとき、いきなり詳細なパラメータを羅列するのはリファレンスの役割。
まずは試しに動かせるチュートリアルがあれば、ユーザーはずっと取り組みやすくなります。
四つの象限を意識するだけで、文書の設計は驚くほどクリアになります。
実践に取り入れるヒント
では、Diátaxisをどのように自作のドキュメントに活かせばよいのでしょう。
まず、既存の文書を四つに分類してみてください。
どの象限が不足しているか、同じ内容が複数の象限に重複していないかを点検します。
新しく書くときは、最初にその文書がどの象限に属するのかを決めるだけで、見出しのつけ方や文体が自然と定まります。
大切なのは、完璧を目指しすぎないこと。
少しずつ枠組みを意識し、書きながら整えていくうちに、ドキュメント全体の質が上がっていきます。
ドキュメントとは、ただ情報を並べるだけでは不十分です。
書く人と読む人のあいだに立つ、優れたフレームワークがあるだけで、伝わる力は大きく変わります。
Diátaxisの考え方を日常にほんの少し取り入れてみると、きっと新しい景色が見えてくるでしょう。