Diátaxis – 技術ドキュメント作成の体系的アプローチ
(diataxis.fr)- 技術ドキュメントはユーザーの状況ごとに異なる役割を果たすべきだという前提のもと、Diátaxisはコンテンツ・構造・形式をあわせて整理するアプローチ
- ユーザーの要求を4つに分け、それぞれをtutorials, how-to guides, technical reference, explanationというドキュメントタイプに対応づける
- 単純な分類表ではなく、何を書くか、どう書くか、どこに配置するかを扱うドキュメント設計フレームワークに近い
- 執筆者とメンテナーもドキュメント品質を判断しやすくなり、軽量で直感的で、特定の実装方法を強制しない点が利点
- Vonage、Gatsby、Cloudflareの事例のように、ドキュメントの探索性と情報構造を改善しようとするチームにとって、実務的な基準として活用できる
Diátaxisが分ける4つのドキュメントタイプ
- Diátaxisは技術ドキュメントを作成・運用するための考え方であり実践方法
- 出発点はドキュメント利用者の要求を理解することであり、そこからコンテンツ、アーキテクチャ、形式に関する原則を導き出す
- ドキュメントの要求と形式は4つに区分される
-
tutorials
-
how-to guides
-
technical reference
- explanation
- ドキュメント自体もこの4つの要求を中心に構成されるべきであり、Diátaxisは3つの問いをあわせて扱う
- content: 何を書くか
- style: どう書くか
- architecture: どう組織するか
-
執筆者とメンテナーのための適用性
- Diátaxisはドキュメント利用者だけでなく、ドキュメントの執筆者とメンテナーにとっても役立つアプローチ
- 軽量で理解しやすい
- 適用が直感的
- 実装上の制約を強制しない
- メンテナーが自分の作業を判断できる品質原則を提供する
- これらの原則は、数百のドキュメントプロジェクトで成功裏に採用された知見としてまとめられている
実際のドキュメントプロジェクト事例
- VonageのGreg Frileuxは、Diátaxisによってユーザーに好まれ、貢献者にとっても追加しやすい社内ドキュメント群を作れたと評価している
- Gatsbyはオープンソースドキュメントを再構成する際、Diátaxisフレームワークを主要なリソースとして活用し、4つの領域が各ドキュメントタイプにおけるユーザー目標の優先順位づけに役立ったと述べている
- CloudflareはCloudflare developer docsの再設計でDiátaxisを情報アーキテクチャの基準とし、新しいコンテンツをどこに置くべきか判断する際にこのフレームワークを参照した
1件のコメント
Hacker Newsのコメント
職業的な書き手ではない立場から見ても、細部はさておき、ここから得た最も重要で基本的な洞察は、すべてを厳密に一度だけ言う必要はないということだった
この考えに触れる前は、ひとつのテキストの流れが「文書全体」の役割を果たさなければならないと思い込み、自分で自分をこんがらがらせていた
読者ごとに同じ情報を別の書き方で示してよいと気づくだけでも大きな助けになる
読者が例どうしの共通項を見つけることになるので、ひとつの例だけで説明するより曖昧さが少なくなる
聖書の箴言におけるソロモンのような著者たちも、こうした手法をよく使っている
要旨では「本論文はYをZと比較評価し、Xが成り立つことを示す」と書き、序論ではAの問題がBのために重要だがXの側面が見過ごされており、Yを評価するとZとは異なる現実的な課題が明らかになると説明し、再び「要するにXゆえにYはZより優れている」とまとめる
関連研究でも、Zのアプローチが何を改善したかを述べつつ、後で示すようにそれでは十分ではないとつなげ、各節で核心メッセージをぐるぐると繰り返し扱うことになる
2週間前に Sequin のドキュメントへこのフレームワークを適用したが、型があること自体がとてもよかった
いまでは文書の流れがずっとよくなり、どこに何を入れるべきかがわかるので、文書の追加や保守もしやすくなった
ただ皮肉なことに、Diátaxis の文書そのものは少し難解で冗長で、何度か読んでようやく感覚がつかめた
チームに説明するときは、圧力鍋のような調理器具を買うことにたとえた: まずクイックスタート（チュートリアル）でだいたいどうやってAからBへ行くのかを見て、その次に好きな特定の料理をどう作るかを探すのがハウツーで、気になる細部が出てきたらリファレンスで豆の種類ごとの正確な調理時間を確認し、圧力がなぜ調理時間を変えるのかや安全装置がどう動くのかまで知りたくなったときに説明資料を読む、という具合だ
おかしなことに、うちのドキュメントは完全に逆で、
How Sequin Worksのような説明から始まっていたエンジニアの自然な衝動は、どう動くのか、なぜそう設計したのかを先に話してメンタルモデルを植え付けようとすることだが、人にはそんな時間も忍耐もない
クイックスタート → ハウツー → リファレンスの流れで世界観に順応してもらい、本当に関心を持ってもらってから説明資料でアプローチを納得してもらうほうがよい
https://sequinstream.com/docs
会社のツールが単なるツールである事実を認めるのが恥ずかしいかのように、「革新的なシナジー体験」みたいな空疎な言い回しで曖昧になったり、逆に「この製品がなぜ存在するのか」を扱う前に細部へ入り込みすぎたりすることが、文書ではよくある
ただし文書内で CDC が繰り返し出てきて、定義を検索する必要があった。これまでのキャリアで CDC を何度も実装してきたが、その略語には馴染みがなかった
流れは結局のところ読者の選択であり、私の頭は全体説明を先に欲しがって、そのあとでハウツーやチュートリアルを探すようにできている
技術文書の執筆者の立場からすると、Diátaxis は DITA に似ている: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html
ただし、こうしたシステムはユーザーが実際に必要としているものを取りこぼすことがある
技術文書が文書プラットフォーム内でのみ使われるなら Diátaxis は長くうまく適合するかもしれないが、同じ情報が UI、ドキュメントポータル、モバイルアプリのように複数の場所で使われうるし、そうあるべきなら、情報をもっと小さな断片に分けてさまざまな方法で組み立てる必要があるかもしれない
これをコンテンツ再利用と呼び、同じコンテンツを複数の場所で使うやり方のことだ
コンテンツ再利用のための情報作成・編集アプローチのひとつは、「every page is page one」という概念で説明されている: https://everypageispageone.com/the-book/
リソースと時間があるなら、プロジェクト開始段階で UX リサーチを勧める。そうすれば後になって、過度に制約の強い情報モデルのせいで息苦しい状況になるのを避けられる
Nielsen/Norman もこの領域を多く研究しており、関連する問題解決に興味深い提案をしている: https://www.nngroup.com/articles/information-foraging/#toc-what-is-information-foraging-2
DITA は task、reference、concept のようなトピック型を区別するが、チュートリアルやソリューションガイドはそうしたトピック型の組み合わせになる
ここでは個々のトピックよりも、もっと大きな成果物に焦点があるように見える
DITA に深く入り込んでいるので複雑さが問題になっていないのかも気になる
コンテンツを再利用可能な断片に分け、DITA や DocBook のセマンティクスでマークアップすれば、大規模言語モデルが「理解」しやすくなるはずだと思うが、その種のデータは見たことがない
今どきは XSL/FO やその親戚たちにしがみついて格闘するより、文書を書くもっとよい方法がある
技術文書作成の分野では、すでに非常に人気があり、かなり標準に近い存在になっている。
ただし、これを行き過ぎるほど推し進めて、文書ページに文字どおりこの4つのカテゴリしか置かない場合があるが、たいていうまく機能しない。
主に、執筆者が「これはガイドなのだから教えることはせず、結果に到達することに集中しよう」といった考え方を保つのに役立つ。
現実には、あまりに厳格な境界は望ましくなく、ガイドの中に多少のチュートリアル要素があっても構わない。
実際、このアプローチが行き詰まるのは、四象限のあいだのつながりが不足しているときだと思う。
たとえばソフトウェアフレームワークで、ガイドから最終的に使うべき特定のクラスやメソッドのリファレンス資料へリンクされていないと、周辺コンテキストをたどるのがずっと難しくなる。
いくつかの具体的なフレームワーク文書がこのように四象限を分けており、その文書群で最もいら立たしい点の1つがまさにこれだ。
他の専門家がいないなら、初心者は「自分で正しいことをやろうとする」よりも、規則に厳密に従うほうがよい場合がある。
初心者は定義上、その判断を下す専門性を持っておらず、経験を積むと定められたルールから外れるべき地点が見え始める。
料理本を見て家庭料理を作るのと、プロのシェフが勘と味見で鍋に材料を放り込むことの違いに近い。
しかし、チュートリアルには説明文を1文たりとも入れてはならないと主張し、規則を文字どおり守るべきだという人と一緒に仕事をしたことがある。
こうしたシステムの危険はまさにそこにある。
「グローバル変数を変更するな」や「関数は短く書け」といったプログラミング原則に似ている。
完璧に合わせる必要はないが、たいていはその反対方向に行くより、その方向へより多く動くほうがよい。
そこで冒頭セクションを Claude に Diátaxis で分類してもらったところ、主に説明であり、一部に参考資料の要素が混ざっていて、Diátaxis の基準では理想的ではないと答えた。
純粋にハイパーパラメータ調整の概念と重要性を説明するセクションと、利用可能なツールや方法を列挙する別個の参考セクションに分けるほうがよいとも言っていた。
しかし続けて、この統合的アプローチがユーザーガイドの文脈ではうまく機能する理由も整理していた。人々が実際に学ぶ流れに沿っており、概念と実装をすぐに結びつけ、基本概念から複雑なツールへと段階的に明らかにし、理論と実務をつないで実用的価値を与えるからだ。
最初の SwiftUI アプリのリリースを終えたばかりの立場からすると、現代の技術業界ではドキュメント化があまりにもお粗末に扱われていると強く感じる。
Apple が解雇した優れたテクニカルライターたちの仕事がひどく恋しく、Apple のエンジニアは本当に文書を書くのが下手だ。
ただし、「教条的」なアプローチには常に慎重だ。現実がそう求めても折れない「聖職者階級」が生まれやすいからだ。
最初にその教義を作った人たちは見事に活用するが、後に続く「聖職者たち」が台無しにして、アプローチを呪いに変えてしまうこともある。
多くの良いアイデアが、過度に硬直した適用によって台無しになってきた。「Agile」がどうなったかを見ればよい。
文書には基本的に保守担当者向けと利用者向けという2つの顔があり、両者では要求が大きく異なるので、おそらく完全に別のチームが扱うべきだ。
複数の場所にある文書が同期から外れる問題もあるが、重要なのは結果である。
複数のインスタンスを効果的に同期できるなら、その文書は利用者にとって効果的で有用だ。
完璧に整形され同期された文書でも、誰にも読まれなければ価値はない。
SNL で Phil Hartman が演じた The Anal-Retentive Chef は、準備に時間をかけすぎて実際の料理実演ができなかったが、技術分野でもそういう姿をよく見る。
ツールチェーンやライブラリは完璧だが、実際には使えないことがある。
文書は、人間の本性や心理、グラフィックデザイン、情報アーキテクチャ、技術インフラ、出版と配布など、さまざまな分野の混合物だ。
ほとんどのプロジェクトでは文書が後回しに扱われるが、要件定義の段階から第一級の考慮事項であるべきだと思う。
文書構造をどこまで深く掘り下げるかには際限がないが、漏れのある箇所を見つけるまでは優れた補助輪として機能する。
良いアイデアに対する一般的な誤解や誤用が、そのアイデア自体を損なうという意味に聞こえる。
むしろ、実際の適用から得られる経験がある。最初のアイデアが実は良くなかったなら幻想を打ち砕くことになるし、悪い実例は、誤って解釈すると失敗につながる曖昧さをあぶり出して、アイデアをより洗練させる。
ただし、悪い実装に慣れた人が増えると、アイデアの人気が落ち、洗練された実装への需要も減る可能性はある。
これはアイデア自体の劣化というより、反共有地の悲劇に近い。
Diátaxis は文書の構造化には素晴らしいが、本当の価値は文書の書き方を単純化してくれる点にある。
すべてを1つの「完璧な文書」に押し込もうとする考えから離れ、ユーザーごとに必要が異なることを認識させてくれる。
チュートリアルは手を動かしながら学ぶためのもので、ガイドは特定の問題を解決するためのものであり、参考資料は素早く参照するためのもので、説明は「なぜ」を掘り下げるものだ。
この明確さだけでも、有用な文書を書けるようになる。
ただし、どんなシステムでも厳格に握りしめすぎると罠になる。
それとも、統合されたパラダイムのようなものがあるのだろうか。
私たちの組織ではこの方式を使っており、導入してから技術文書が完全に別次元になった。
ページ所有権と各ページ所有者による定期レビューまで加わって、私が見た中で唯一成功した技術文書化の取り組みになっている。
divio が使っている図のほうが、ずっと直感的だと思う: https://docs.divio.com/documentation-system/
ただし、Diátaxis のほうが各意味をより包括的に文書化しているように見える
Diataxis.fr にある Divio のリライト版はグラフィックがそれほど雑然としていないが、本質的には Divio で使っていたものと同じだと思う
この2つの資料は、それぞれのウェブサイトの文脈で提示されているアイデアに関する限り、実質的に同じ文書だと見てきた
どの点がより直感的なのか知りたい
このアイデアは気に入っているし、作った人には PyConUK で何度か会う幸運もあった。才能があり、とても親切な人だ
ただ、文書の複数の領域をここまで厳密に区分することには留保がある
あるスプリントで、私が準備していた文書が複数の様式を混ぜているので受け入れられないと言われたことがある。ちなみに Daniele が言ったわけではない
権威を振りかざすつもりはないが、20年以上教師として働いてきたので、人が物事を成し遂げながら同時に理解も深められるように説明し、学習の足場を組む方法についてはそれなりの感覚がある
完全な硬直性さえなければ、これは文書をどう作るか、そして各文書タイプが何をすべきかを決めるための優れたツールだ
文書の例、たとえば numpy では、「空から降ってきた魔法」のような例より、はるかに良い題材を選べることがよくある
うまく選ばれた1つの例は、使い方を示しながら、コーナーケースや注意点まで含めて多くの学びを与えられる
理論上は正しいと思うが、同意しにくい。言葉同士が近すぎる
私には「チュートリアル」「ハウツーガイド」「説明」は、実質的にほとんど同義語のように感じられる
深く考えれば各カテゴリに妥当な理由があるのは分かるが、意味的に近すぎて頭が違いを見分けられない
何かがどう動くのか知りたいときに「チュートリアル」と「ハウツーガイド」が並んでいたら、どちらを押せばいいのか分からず、結局最初のほうを押してしまう
自分に合う用語を探してみるのも有益な練習かもしれない
あるいは、行動/認知、つまり「すること vs 考えること」と、習得/適用、つまり「学習中 vs 作業中」の区別として理解してみることもできる
チュートリアルとハウツーガイドを区別する専用ページもある: https://diataxis.fr/tutorials-how-to/
最も単純な区別の1つは、チュートリアルは Stack Overflow ではできないものだという点だ
チュートリアルは教師が定めた授業計画に沿って進み、学習者自身が知らないと気づいていない部分を埋めていく過程だ
Stack Overflow では質問しなければならないが、チュートリアルは、まだ何を尋ねるべきかすら分からない人のための資料だ
単純な作業をどう行うかという人気の質問も多いが、その形式に合うには、漠然と助けを求めるのではなく質問をしなければならない: https://meta.stackoverflow.com/questions/284236
Diátaxis の文書は違いをかなり効率よく説明している: チュートリアルは学習志向の体験、ハウツーガイドは目標志向の指示、参考資料は情報志向の技術的記述、説明は理解志向の議論だ
この体系における「チュートリアル」は日常語ではなく、専門用語として読めばよい
心理学者が言う「depression」が日常的な意味と完全には一致しないのと似ている
それでも Type I-IV チュートリアルと名付けるよりはましだ
講義は説明であり、チュートリアルや実習はガイド付きの体験で、Microsoft の架空の企業 Contoso を思い出す
ハウツーガイドは解決策を検索したり ChatGPT に尋ねたりするときに必要なもので、参考資料は類語辞典、百科事典、取扱説明書のようなものだ
ビデオゲームには組み込みのチュートリアルがあるが、難しいパズルには依然として攻略ガイドが必要で、キー設定は参考資料で確認する