準備フェーズ
最重要なのは読み手の理解
準備フェーズで最も重要視すべきことは「読み手の理解」です。ドキュメントの読み手は何らかの課題感を持ってドキュメントを読みに来ているはずです。たとえば、APIマニュアルであれば、ユーザーがAPIの使い方や認証・認可を通す方法を調べにきているはずです。あるいは、PRD（Product Requirements Document）であれば、開発者が設計や実装の検討に向けて、プロダクトの目的や解決する問題を理解するために読みに来ているはずです。
この読み手の課題を効果的に解決するためには、「読み手は誰で」「何のために」ドキュメントを読みにきているのかを徹底的に理解する必要があります。読み手の理解を外してしまうと、無価値なドキュメントが誕生してしまいます。誰の課題も解決しておらず、かつ保守のコストが継続的にかかり続けてしまうようなドキュメントです。
読み手を理解する方法
では、どうすれば読み手を理解できるのでしょうか？
理解するための方法は書き手の携わっているシステムやサービスの環境にかなり依存します。たとえば、リリースされてから数年が経過しているようなサービスであれば、ユーザーインタビューのメモや、過去のサポート履歴など、多くの情報が残っていることでしょう。ユーザーがどんなレベルで、何を課題としてドキュメントを読みにきているのか、ヒントとなる知識が多くみつかるはずです。
一方で、未リリースのサービスであれば、過去の情報量は限られたものになるでしょう。それでも、想定顧客へのインタビューや、社内のチャットで議論したログなどから、ユーザー像がある程度は見えてくるはずです（※仮に見えてこなかったとしたら、ドキュメントを書く前にまずユーザー像を洗い出すために、インタビューを重ねる必要があるかもしれません）。
読み手の理解がおぼろげに浮かび上がってきたら、次は検証です。あくまで、ここまで作ってきた「読み手」は仮説にすぎません。実際にその読み手がいるのかどうかを確かめる必要があります。「読み手の理解」を検証するための最高の方法は、読み手と直接対話してみることです。
もしかしたら、「読み手と直接対話する機会がないかもしれない」と開発者は考えているかもしれません。しかし、社内にはいろいろな方法が隠れているはずです。たとえば、カスタマーサクセス経由で現在の顧客にあたってみるほかに、インタビュー履歴から話をしてもらえるユーザーを見つけられるはずです。
理解した知見をまとめておく
読み手と対話できたら、たくさんのインサイトが得られるはずです。たとえば「この機能の説明は理解しにくかった」「どのドキュメントを読めばいいか混乱した」といった具体的なフィードバックや、「こういう使い方もあったら便利だった」といった新しいアイデアなどです。
これらの知見をまとめるためには、何らかの形式で構造化して残しておくと良いでしょう。インタビューログそのままでは、情報量が多すぎて短時間で解釈できないためです。構造化して残すための代表的な方法は、たとえば次のようなものがあります。
- ユーザーペルソナ
- ユーザーストーリー
- カスタマージャーニーマップ
ユーザーペルソナは、典型的なユーザーの特徴や行動パターンを仮想（あるいは実在）の人物像としてまとめたものです。これにより、書き手が読み手を具体的にイメージしやすくなります。ペルソナにはたとえば、以下の情報が含まれます。
- 基本的な属性（得意な言語や技術レベルなど）
- 課題
- 開発環境
- プロダクトやサービスの利用シーン
例えばこのようなイメージです。
ユーザーストーリーは、ユーザーの視点から機能や要件を簡潔に記述したものです。「〜として、〜したい。なぜなら〜だからだ。」という形式で書かれます。これにより、ユーザーのニーズや目的を明確に、かつ迅速に把握できます。
カスタマージャーニーマップは、ユーザーがプロダクトやサービスと関わる一連の体験を時系列で可視化したものです。これにより、ユーザーの行動や感情の変化を全体的に把握し、改善点を見つけやすくなります。
上記を複数組み合わせても問題ありません。重要なのは、何らかの形式で使いやすいように知見をまとめて構造化しておくことです。
知識の呪い
最後にドキュメントの準備フェーズで意識すべきTipsとして、知識の呪いを紹介します。
知識の呪い（Curse of knowledge）とは、ある分野に詳しい人が、その分野に詳しくない人の視点に立って考えることが難しくなる認知バイアスのことです。「なんだ、当たり前じゃん」と思われるかもしれませんが、意外と職場で経験しているのではないでしょうか。たとえば、同僚がよくわからない社内用語を使っている、開発環境の構築手順を部分的にしか書いていない、といった事象です。この事象は、同僚に悪意があるから発生しているわけではありません。むしろ、「これぐらいは理解しているかもしれない」と前提知識を見誤っているからこそ起きているのです。
ドキュメントを効果的に作成するためには、この知識の呪いを断ち切る必要があります。そのために重要なのが、ここまで説明してきた読み手の理解なのです。
まとめ
本記事では、ドキュメントライティングの重要性と準備フェーズについて解説しました。主なポイントは以下の通りです。
- ドキュメントは開発組織・チームを効果的にスケールさせ、維持するために必須である
- ドキュメントライティングは、準備、作成、運用の3フェーズに分けられる
- 準備フェーズでは、読み手の理解が最も重要である
- 読み手を理解するためには、既存の情報を活用するとよい
- 読み手の理解の検証には、読み手（ユーザー）と直接対話するのがいちばん効果的である
- 得られた知見は、ユーザーペルソナやユーザーストーリーなどの形で構造化して残すとよい
ここまでの情報を土台として、次回では、ドキュメントライティングの「作成フェーズ」以降に焦点を当てて、実際にドキュメントを書き始める際の具体的な方法やテクニックを扱います。
