こんにちは。クリエイション開発部の丸山@h13i32maruです。
みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。
そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏
🕵️メンタルモデルの原則
良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼びます（私が勝手に呼んでいるだけなので、ググっても出てこないかも）。
💡メンタルモデルを構築すると推測可能になる
メンタルモデルとは「これをするにはこうする。こうしたらこうなる。」というように動作や結果をイメージできるような心のありようです。あるツールについてメンタルモデルを構築できると、ドキュメントを読むこと自体が楽になります。また、いずれはドキュメントをほとんど読まなくてもツールを使いこなせるようになります。
例えば使い慣れたプログラミング言語であればドキュメントを読まなくても「こういう場合はこう書けそう」とか「多分このへんのドキュメントみたら使い方書いてありそう」となると思います。これはそのプログラミング言語に対してメンタルモデルを構築できているからです。
ようするにメンタルモデルを構築するとはその対象について色々なことを推測できるようになるということです。なのでメンタルモデルを構築できるドキュメントは有益なドキュメントだと考えています。
ではどのようにすれば「メンタルモデルを構築できるドキュメント」を書けるのでしょうか？それには以下のことを意識してドキュメントを書くことが重要だと考えています。
- 読者の現在のメンタルモデルや目的
- 演繹的・帰納的な説明
📝メンタルモデルの有無や目的に応じてドキュメントをかき分ける
ドキュメントを読む人は様々です。そのツールを使い始めようとしている人、特定の使い方を探している人、100%使いこなしたいと思っている人、などなど。そういった読者に合わせたドキュメントを書くことが重要です。このときに読者はどれくらいメンタルモデルを構築済みかも重要になってきます。
例として「初めて使う人向け」「特定の使い方を探している人向け」「もっと使いこなしたい人向け」のドキュメントについて説明していきます。
① 初めて使う人向け
初めてツールを使う人の場合メンタルモデルは全く構築されておらず、目的はとりあえずさくっと使ってみるというのがほとんどだと思います。そういう読者のためにセットアップ方法とすごく基本的な使い方のドキュメントとして「クイックスタート」や「チュートリアル」を用意するのがよいでしょう。
このとき注意すべきことはメンタルモデルが全く構築されていないので、多少冗長でも丁寧な説明をすることです。そうしないと思わぬところでハマってしまうことがあるでしょう。ただし、ツールの外側のことについてはメンタルモデルが構築されていると思うのである程度省略してもよいと思います。例えばJasperであればGitHubやMacアプリのインストール方法などはサラッと書くにとどめました。
② 特定の使い方を探している人向け
特定の使い方を探している人はある程度メンタルモデルが構築されています。なので「こういうことをするには、多分こういう機能がありそう」と思いながらドキュメントを読み始めます。よって「こういうことをするには」に相当するような「よくあるユースケース」や「サンプル集」を用意するのが良いでしょう。
③ もっと使いこなしたい人向け
こういう人はメンタルモデルがバッチリ構築済みなので、網羅的なドキュメントを用意するのが良いでしょう。いわゆる「リファレンス」や「辞書」みたいなものです。一つ気をつけるべきアンチパターンは「APIリファレンスしか用意されていないライブラリのドキュメント」みたいなものです。これは「もっと使いこなしたい人向け」以外の読者のメンタルモデルや目的を完全に無視していると思います。（それで問題ない場合ももちろんありますが）
ちなみにJasperでは以下のようにドキュメントの入り口を分けることによって、異なる読者を適切なドキュメントに誘導しています。
🙆演繹的・帰納的な説明により推測を可能にする
人間がものを推測するときは大きく分けて演繹的な方法と帰納的な方法があります。
演繹的というのは「プログラミング言語には四則演算がサポートされている。TypeScriptはプログラミング言語である。よって、TypeScriptでは四則演算が使える」のような論理的な因果関係で推測することです。一方で帰納的というのは「TypeScriptは加算・減算・乗算が使える。なので除算も可能なはずであり、四則演算を使えるだろう」のようにいくつかの具体例をもとに推測することです。
よって演繹的・帰納的な方法で説明されたドキュメントを読むことで、そのツールの使い方や目の前のドキュメントには書かれていないことなどを推測できるようになっていきます(=メンタルモデルを構築する)。
例えばJasperでは「JasperはGitHubの検索クエリと完全互換があります」という説明をいれています。これによって読者は「ということはGitHub検索で使っていたあれもつかえるのでは？」という推測を可能にします。ほかにも「リポジトリ指定するにはこう、ユーザ指定するにはこう、ラベル指定するにはこう」という説明をしています。これによって「チーム指定する方法もあるのでは？」という推測を可能にします。
演繹的・帰納的という言葉を使いましたが、ようは「前提としていることを説明」「繰り返しやパターンで説明」を意識してドキュメントを書くとよいという話でした。
というわけでドキュメントを書く上での「メンタルモデルの原則」について紹介でした。良いドキュメントは著者も読者もwin-winなので、いいもの書いていきましょう。