よい製品でもガイドやチュートリアルが難解だと使ってもらえない、ではドキュメントの正しい作成方法とは？

どんなに優れた製品でも、その製品のドキュメントが難解だとユーザーの拡大は難しいもの。そんなドキュメントの「正しい作成方法」について、ウェブアプリのビルドサービスを提供するDivioが解説しています。

The documentation system — Documentation system documentation
https://documentation.divio.com/

よい製品でもよいドキュメントがなければユーザーは増えないと多くの人が認識しているにもかかわらず、「正しいドキュメント作成方法」を知らないために、ドキュメント作成に失敗している事例が後を絶たないとDivioは指摘。Divioはドキュメントを「実践的か、理論的か」「学習時に役立つか、作業時に役立つか」の2軸に当てはめ、「チュートリアル」「HowToガイド」「リファレンス」「説明・議論」の4つに分類しています。

◆チュートリアル
チュートリアルは「ある製品を利用する一連のステップを体験できる」もの。チュートリアルがなければ製品を理解するきっかけが生まれないため、新しいユーザーの獲得はうまくいかないとDivioは指摘しました。チュートリアルで重要なのは、「読み手が楽しく進められ、自信を持てる」こと。「実際に手を動かすものになっている」「すぐに成果を与える」「さまざまな環境で動作確認をする」といった、読み手がスムーズに自信を持てるような仕組みが必要になります。

逆に、読み手の自信につながるのであれば、「手順が通常のものとは異なる」「できることのすべてを網羅していない」といった点は問題にならないとのこと。むしろ初めてのユーザー向けにわかりやすい手順を用意したり、手順に含む機能を制限したりすることはいいことだとDivioは語っています。

◆HowToガイド
HowToガイドは「実際に起こった問題を解決に導く」もの。料理で例えると「レシピ」にあたります。チュートリアルとは異なり、書き手は読み手の知識や理解をある程度前提にすることが可能。HowToガイドでは「目的」が最も重視されるので、「問題解決に至るまでの道筋を順序どおりに示す」「ある特定の問題にテーマを絞る」「明確なタイトルを付ける」といった工夫が必要とのこと。

HowToガイドでは読み手が目的を達成できればよいので、物事を詳細に説明することは避け、異なる環境に対しても適用できるような柔軟性を持たせるなど、実用的なものにすべきと説明されています。

◆リファレンス
リファレンスは関数やAPIの仕様といった「製品の技術的な記述」です。リファレンスは機能をただ記述するだけのものであり、料理で言うと「食物の品種や特徴が記述された百科事典のページ」になります。リファレンスは形式的かつ要点を押さえておく必要があり、「文章構造や文体をそろえる」「説明や推論を含めない」「正確に記述する」といった点を意識すべきとのこと。

また、文章構造をコードベースとそろえることで、コードの変更によるメンテナンスコストを下げることができるとDivioは説明しています。

◆説明と議論
説明と議論は「特定のトピックを明確にする」もの。料理の例えでは「料理の歴史についての本」にあたります。説明と議論は他の分類と比べて省かれがちですが、製品をその背景まで含めてさまざまな視点で理解するための手助けとなる存在です。この分類では「なぜ製品がそうなっているのかを、技術的制約や歴史を踏まえて説明する」「現状の仕組みの代替案を示す」「反対の意見を検討・議論する」といった、他の分類がカバーしていない部分をカバーすべきとのこと。

なお、Divioが提唱しているドキュメントに対する考え方は、ウェブアプリケーションフレームワーク・Djangoのドキュメントなどが取り入れています。

Django documentation | Django documentation | Django
https://docs.djangoproject.com/en/3.0/#how-the-documentation-is-organized