最近ドキュメントを書く機会が増えてきたこともあって、良いドキュメントを書くにはどうすればいいかというのを改めて考えたので、考えたことを残しておく。

誰のために書くか（対象読者）を考える

これが最も重要。
本を読んでいると、まえがきなどに想定読者が明示されていることがあると思うが、それと同じようにドキュメントも誰のために書くかを最初に考える。

これは読み手と書き手の双方にメリットがある。

• 読み手：そのドキュメントを読むべきかどうかの判断ができる
• 書き手：ドキュメントに書く内容を考える時の指針になる

特に書き手側のメリットが大きいと思っており、対象読者を明確にすることで記載するドキュメントの構成や内容が決まり、結果的に質が上がると思う。新人にむけて書くのか、ベテランにむけて書くのか、あるいは自分用に書くのかなどで、記載すべき内容やその詳細度が変わることは想像に難くないと思う。

対象読者が曖昧だったり特に考えられていないドキュメントは、読み手によっては中途半端なものになってしまう可能性が高い。

対象読者に何を得てもらいたいかを考える

対象読者を決めたら、書き手の人は「ドキュメントから何を得てもらいたいか？読んだあとにどんな状態になってほしいか？」を考える。

これを明確化することで、ドキュメントに書くべき内容が自ずと決まる。ここで設定したゴールを満たす内容にすれば良いだけだからである（といっても、何を書けばそのゴールを満たせるかを考えるのはなかなか難しいが..）。

例えば、チームに加わる新人のためにドキュメントを書くならば「新人がスムーズに仕事を始められるようにしたい」とか「チームがどんなふうに仕事をしているかを知ってもらいたい」、「読んだあとに実際の業務を始められる状態になってほしい」などが挙がると思う。

また、SaaSなどのサービスを提供する側が、利用者向けに書くドキュメントならば「利用者にスムーズに利用を開始してもらい、継続的に利用してもらえるようにしたい」とか「困ったことがあったときに自己解決してもらえるようにしたい」などだろう。

対象読者がその状態になるために何を書くかを考える

対象読者にドキュメントから得てもらいたいものが決まったら、次はその目的を満たすために何を書けばいいか考える。ここはなかなか難しく、色々と考えを巡らせないといけないところになるかと思う。

例えば、チームに加わる新人向けで、スムーズに仕事を始められるようにすることが目的ならば次のような内容が自分だったら思い浮かぶ。

• チームが何を目指しているか
• どんな仕事をしているのか
• 一週間のスケジュール
• 担当する業務の概要から詳細まで
• 困ったときの問い合わせ先
• etc..

※ 余談ではあるが、ここは過去の自分の良かった体験だったり、実際にわかりやすいと感じたドキュメントを逆に分析して内容を考えてみるとおもしろいかもしれない。

ドキュメントの構成を考える

記載する内容が決まったら、最後にその全体的な構成を考える。

経験的には、基本的に記載内容でカテゴライズしてドキュメントを分けつつ、ドキュメント自体は概要から詳細に流れる形で書くとわかりやすくなることが多いと思う。

おわりに

あんまりまとまっていないけど、ドキュメントについて考えたことをざっくり残してみた。 結論、逆算思考的にドキュメントを書くと良いモノになるんじゃないかなというのが最近思ったこと。

ドキュメントは書きすぎてもメンテナンスコストがかかるので、必要を感じていないならばドキュメントは書かないほうが良いんじゃないかとすら思うようになったが（やや極論）、一方で良い内容のドキュメントはやはり読み手の助けになることがあるなというのもまた事実だと思うので、できるだけ質の良いドキュメントだけを残すようにしたいと思うようになり、このようなことに少し考えを巡らせてみた。