価値のある技術文書を書くためには読み手の想定を立てるべき
この記事はなに?
現在、私は「社内で、カジュアルに、技術情報やその他ノウハウを共有するにあたって、 より価値がある情報を発信する技術」の情報を集めています。
その動機は以下です。
- 去年入社した新入社員にそう言うスキルを高めてもらって、有用な情報をもっと発信してもらいたい。
- ついでに自分もそう言うスキルを高めたい。
その中で見つけた以下の本が役に立つ内容だったので、自分なりの視点を交えて紹介します。
というか、この本から得た気付きをきっかけに、普段自分が文書を書く時に考えている事を主張します。 （なので、本の内容とはかなり乖離した記事になっています。）
はじめに
この記事では以下の主張を行います。
- 技術文書は、読み手が必要としている情報を書くべき。また、そのためには読み手がどのような人なのか想定する必要がある。
これ以降の章で、「なぜそのようにすべきかという理由」と、「どうすればそように出来るかという自分なりの方法の紹介」をします。
技術文書は読み手が必要としている情報を書くべき
技術文書を書く時に重要な事の1つとして、
- 書き手が書きたい事ではなく、読み手が必要としている情報を書くべき
という点があります。
いくら書き手が満足しても、読み手が必要としてる情報を手に入れられなければ価値は生まれないためです。
とは言え、いくら読み手が必要としていても、書けない情報は書けないので、こういうエリアの情報を書いていく事が必要になります。
以下で、その方法を紹介します。
まず想定読者が必要
読み手が必要としている情報を書くのにあたって、 まず読み手を想定する 事が重要です。
例えば あるプログラミング言語の解説について、「文法もおぼつかない初心者」から「その言語のコミッターのような上級者」にまで全員に価値を提供できる文書をつくるのは困難です。
- 初心者にとって役に立つ情報は、上級者にとってはもう知ってる情報ですし、
- 上級者にとって役に立つ情報は、初級者にとっては理解不能だからです。
あらゆる人間を対象にした文書は誰にも適切な情報を提供できません。
想定読者を設定して対象を絞れば、より適切な情報を提供できます。
読み手のニーズと書き手のシーズをすり合わせる
読み手が必要としている情報を書くには、文書を書く前の段階での工夫が必要です。
つまり、 「そもそも何について文書を書くか」 と考えている段階での工夫です。
私は、 「そもそも何について文書を書くか」を考える時に以下のどちらかの出発点から始めます。
- 「書き手が提供できる情報」を出発点にする。
- 「読み手」を出発点にする。
必要なアプローチはa.とb.とで異なるので、以下の章で分けて解説していきます。
「書き手が提供できる情報」を出発点にした場合
「書き手が提供できる情報」を出発点にした場合、以下の質問のどちらか（または両方）を自問自答してみます。
- 「この情報を知って一番役に立つのはどんな人か?」
- 「この情報を知らなければいけないのはどんな人か?」
この質問への答えを、想定読者として設定する事が出来ます。
例1
手前味噌になってしまうのですが、以前自分が書いた記事を例に解説してみます。
この記事の場合は、まず
という「書き手が提供できる情報」が出発点になっています。
想定読者を設定するために、以下の質問を自問自答してみました。
- 「この情報を知って一番役に立つのはどんな人か?」
この記事の場合は、以下のような人に役立ちそうだと考えました。
「rubyに触れたことがあって、rubyの文法は理解しているけど、 オープンクラス／すべてがオブジェクト／ダックタイピングのようなruby特徴的な挙動を理解していない人 」
これが想定読者になります。
例2
例えば仮に、運営中のサービスでトラブルが発生し、トラブルの原因を突き止め、再発防止策を実施したのなら、
- 「この情報を知らなければいけないのはどんな人か?」
と、自問してみて、
「このサービスを担当しているエンジニア全員と、自社内の類似サービスを担当しているエンジニア全員」
という答えが出たなら、それを対象読者として設定する。と言った事ができます。
「書き手が書ける情報」を出発点にした場合は、 「書き手が書ける情報」は固定したまま、それに合う対象読者を探していくという事です。
「読み手」を出発点にして書くには?
読み手が最初から明らかな場合もあります。
ある誰かが抱える課題を解決するような情報のアウトプットが必要な場合などです。
この場合は以下を自問自答します。
- 「この想定読者にとって一番役に立つ情報は何か?」
- 「この想定読者が知らなければならない情報は何か?」
この答えが「読み手が必要としている情報」です。
例
- 「デザイナーさんに、Gitを使って画像やマークアップ、アニメーションなどのリソースをpushしてもらいたい。 そのためにGitの使い方を説明する文書を書きたい」
この場合は、
- 「この想定読者にとって一番役に立つ情報は何か?」
- 「この想定読者が知らなければならない情報は何か?」
を自問して、
Gitの操作方法や、注意点といった情報、また、リポジトリの運用ルール
と言った情報が「読み手が必要としている情報」である事が分かります。
「読み手が必要としている情報」を出発点にする場合には、 「読み手が必要としている情報」は固定したまま、それに合う情報を探していくという事です。
文書を書く時の自問自答
さて、ここまでで、「そもそも文書に何を書くべきか」と「対象読者の設定の仕方」について主張しました。
ここで、「対象読者の設定」と「何を書くか」が決まった後、実際に文書を書く時に自分が使っている自問自答集を紹介します。
- 「対象読者がすでに知って、はぶくべき情報は何か?」
- 「対象読者がまだ知らない、説明が必要な情報は何か?」
- 「この情報は、対象読者にどんな風に役に立つか?」
- 「どんな効能を説明すれば、対象読者が興味を示してくれるか?」
- 対象読者に文書を読んでもらうために、何の役に立つ文書なのか、文書の冒頭でしめします。
- 「対象読者以外に対して、『あなたは対象読者ではない』と示すために何を書いておくべきか?」
- 対象読者以外の人が文書を読んだ時、文書の冒頭で「自分は対象読者では無い」という事に気づけるようになっていれば、その人の時間を無駄にせずにすみます。
まとめ
- この図で、赤と青が重なっている部分について情報を発信すると価値があります。
- あらゆる人間を対象にした文書は、誰の役にも立ちません。対象読者を絞る必要があります。
- 「書き手が提供できる情報」を出発点に文書を書く場合は、「誰に届けたら一番価値がでるか?」を考えます。
- 「読み手」を出発点に文書を書く場合は、「何を届けたら一番価値がでるか?」を考えます。
