필사 모드: Diátaxisを四つのフォルダと誤解する理由 — ひとつの文書に二つのモードを混ぜるとなぜ崩れるのか

• チュートリアルを開いて30分でタブを閉じたことがあるなら
• フォルダを四つ作ることは適用ではありません
• 四つである理由は二つの軸にあります
• 羅針盤 — 段落ひとつに二つの問いだけを投げる
• もっともよくある混同はチュートリアルとハウツーのあいだで起きます
• 二つの状態は正反対のものを要求します
• 説明がリファレンスに染み込む経路
• 今週できること — 一段落、一コミット
• まとめと出典

チュートリアルを開いて30分でタブを閉じたことがあるなら

初めて使うライブラリの公式チュートリアルを開いたとします。1番の項目でインストールをさせ、2番で例を実行させます。ここまでは良いところです。ところが3番の項目が急に「この値は三つの方式で設定でき、本番では二つ目を推奨します」で始まります。三つのうち何を選べばよいか分からない状態で、選択肢が三つ与えられます。4番では内部の動作原理が二段落現れ、5番はまたコマンドに戻ります。

この文書は間違った情報を含んでいません。文章もまともです。ところが読む人は30分ほど経ってタブを閉じます。文書チームがこの事実を知る経路はたいてい「文書が足りない」というフィードバックで、そのフィードバックを受けてやることはたいてい内容を増やすことです。すると次の人は25分でタブを閉じます。

フォルダを四つ作ることは適用ではありません

この問題に名前を付けたのがDiátaxisです。チュートリアル、ハウツーガイド、リファレンス、説明の四つに文書を分けます。広く知られ広く引用されますが、実際のチームで起きる適用はたいていここで止まります。文書リポジトリにフォルダを四つ作り、既存の文書をその下へ移して、おしまいです。

ところがフレームワークを作った側が、この方式を明示的に止めています。Diátaxisのワークフロー文書は、始めるときに文書を四つの区画に分ける必要はないと言い、中身のない空の四つのセクションを作ることについては、そうするなと釘を刺します。構造は改善の結果としてあとから現れるものであって、改善のために先に課すものではないということです。著者はこれについて、Diátaxisは文書の構造を内側から変えるのだと表現します。

四つである理由は二つの軸にあります

なぜよりによって四つなのかが重要です。三つでも五つでもない理由がないなら、これはただの便利な分類であり、便利な分類は曖昧な文書の前で何の助けにもなりません。

Diátaxisの根拠となる文書は、技術を使う人を二つの軸に置きます。ひとつは行動と認知です。どんな技術でも、何をするのかについての実践的な知と、何が真なのかについての理論的な知を同時に持ちます。もうひとつは習得と適用です。人は技術を身につけている最中か、すでに身につけた技術を使っている最中かのどちらかです。勉強している状態と仕事をしている状態と言い換えてもかまいません。

二つの軸が互いに独立なので、象限は必ず四つになります。学習の欲求はチュートリアルが、目標達成の欲求はハウツーが、情報の欲求はリファレンスが、理解の欲求は説明が引き受けます。四つは恣意的に選んだ数字ではなく、領域を余さず覆う最小の個数です。

羅針盤 — 段落ひとつに二つの問いだけを投げる

地図は覚えやすいものの、曖昧な文書の前では直観がよく外れます。そこでDiátaxisは羅針盤という判定表を別に用意します。問うべきことは二つだけです。

重要なのは、この表を文書単位ではなく段落単位でも使えるという点です。実際にDiátaxisは、文と単語のレベルでも当てはめてみるよう勧めます。先ほど見たチュートリアルの3番の項目をこの表に入れると、すぐ答えが出ます。三つの設定方式を並べた部分は認知を扱い、仕事をしている人へ向いているのでリファレンスです。本番での推奨理由は認知でありながら勉強している人へ向いているので説明です。ひとつの文書のなかに三つのモードが入っていたわけです。

もっともよくある混同はチュートリアルとハウツーのあいだで起きます

Diátaxisは、ソフトウェア文書でもっともよくある混同がチュートリアルとハウツーのあいだの混同だと指摘します。理由は単純です。二つは見た目がほとんど同じです。どちらも番号の付いた段階を提示し、どちらも順番どおりに従えば成功すると約束し、どちらも手を動かさない読者には役に立ちません。

違いは形式ではなく、仕える必要にあります。チュートリアルは勉強中の人を、ハウツーは仕事中の人を仕えます。ここでよく出てくる二つ目の誤解が、チュートリアルは基礎、ハウツーは応用という区分ですが、これも間違いです。文書の原文は、ハウツーが基礎的な手順を扱えるし扱うべきだと言い、逆にとても熟練した人のための難度の高いチュートリアルもありうると言います。分かれ目は難易度ではなく、読者が勉強中なのか仕事中なのかです。

二つの状態は正反対のものを要求します

混ぜると崩れる理由がここから出てきます。二つの状態が要求するものが互いを排除するからです。

• 選択肢: チュートリアルは分かれ道を作りません。まだ選ぶ能力のない人に選択肢を与えると、その場で止まります。逆にハウツーは分かれなければなりません。現実は条件が多様で、条件別の分岐がないガイドは現場で役に立ちません。
• 責任: チュートリアルで問題が起きたら、それは著者の落ち度です。学習者が失敗しないよう環境を統制しておかなければなりません。ハウツーではユーザーが自分の状況に責任を持ちます。
• 安全: チュートリアルはいつでも最初へ戻れなければなりません。ハウツーはそういう保証ができません。一度で合わせなければならない作業がよくあります。
• 説明: Diátaxisは、チュートリアルは説明する場ではないと言い切ります。理由を伝えたいという衝動が、教える人にとってもっとも勝ちにくい誘惑だとも付け加えます。原文の表現を借りれば、教えることの第一の規則は「don't try to teach」です。

だからチュートリアルの3番の項目に選択肢を入れた瞬間、その文書は二つの読者の両方にとって悪くなります。勉強している人には決定を強い、仕事をしている人には必要な分岐をすべて見せもしません。

説明がリファレンスに染み込む経路

残り二つのモードのあいだでも同じことが起きますが、こちらははるかに静かです。Diátaxisはその経路を具体的に指摘します。リファレンスに例を入れること自体は正当です。問題は、例が面白いので、書いているうちに、なぜこうなるのか、こうしたらどうなるのか、へとどんどん広がっていくところにあります。

結果は両方の損です。リファレンスは寄り道に隠れて探しにくくなり、説明は他人の家に居候しているせいでまともに展開できません。判定の基準はまたひとつです。これは仕事の途中に開いて見るものなのか、それとも仕事から一歩下がって考えるときに必要なものなのか。

リファレンスなのか説明なのか迷うときに使いやすい経験則もあります。退屈で記憶に残らなければリファレンスの可能性が高く、一覧や表に整理されるものもたいていリファレンスです。逆に、散歩しながら誰かに聞かれたときの答えになりそうな話であれば説明です。

今週できること — 一段落、一コミット

Diátaxisの作業のやり方は、大きな絵を描くなという側です。計画を立てて一度に移す代わりに、次の四段階を繰り返せと言います。

1. 何でも選ぶ。 問題を探して彷徨わず、いま開いているファイル、たった今読んだページを見ます。なければ無作為に選びます。
2. 吟味する。 ページより小さいほど良いところです。段落ひとつ、文ひとつでもかまいません。これはどんな必要のためのものか、その必要をどれだけよく満たすか、何を足すか移すか消せば良くなるか。
3. ひとつだけ決める。 いますぐ改善になる次の行動をひとつ選びます。
4. やって終える。 そのひとつをやってすぐコミットするか配備します。もっとやらねばとは感じません。

自分のチームへ持ち込むなら、こう始められます。今週もっとも多く開かれた文書をひとつ開き、段落ごとに先ほどの羅針盤の二つの問いを投げてタグを付けます。タグが二種類以上出た文書があれば、そのうちひとつだけを選んで別の文書へ移し、元の場所にはリンクだけ残します。このとき移す先の文書がまだなければ、空のフォルダを作らずに文書を一つ作ります。この違いが、先ほど止められたあの誤りを避ける地点です。

文書が終わらないという事実は変わりません。Diátaxisは文書を育つ植物にたとえながら、終わりはしないが段階ごとに完結してはいられると言います。今週ひとつの段落を移した文書も、その状態で完結しています。

まとめと出典

一行に縮めるとこうなります。Diátaxisは文書を分類する規則ではなく、ひとかけらの文章が誰のどんな状態に仕えるのかを問う規則です。フォルダ四つはその問いを代わりにしてくれません。

• Diátaxis公式サイト — フレームワーク本体。以下の項目はすべてこのサイトの文書です。
• Foundations — 行動と認知、習得と適用という二つの軸、そして象限が四つである理由
• The compass — 二つの問いで判定する表
• The difference between a tutorial and how-to guide — 選択肢・責任・安全・説明についての対比、基礎と応用という誤解
• The difference between reference and explanation — 説明がリファレンスへ染み込む経路と経験則
• Diátaxis as a guide to work — 空のセクションを作るなという警告、四段階の作業ループ、完結と終了の区別
• Tutorials — 教えようとするなという原則と、説明という誘惑
• 文書の原文はevildmp/diataxis-documentation-frameworkリポジトリでそのまま読めます。この記事の引用と要約は、そのリポジトリの原文を直接確認したものです。