はじめに
いきなりですが皆さんはドキュメントを書くのが得意なほうでしょうか？
例えばプロダクトのREADMEや仕様書、社内マニュアル、Qiitaなどの技術発信系の記事など…ドキュメントを書く機会は多かれ少なかれあると思います。
私はドキュメントを書くのがとても苦手だなーと思っています😔
どう書いたらわかりやすいんだろう…と考えてムダに時間がかかりすぎてしまうこともしばしば…
書く機会以上に読む機会のほうが多いので、ほかの人のドキュメントを見て（理解しやすい文書構造だな）とか、（わかりやすい言い回しだな）と思うことがよくあります。
私も良いドキュメントを書けるようになりたいと思ったので「良いドキュメントの書き方」についてインプットしたことをまとめます。
個人的な結論
- 良いドキュメントを書くために気をつけたいポイント
- できるだけ具体的に書く
- 要点を先に言う
- どこに何がかいてあるかわかりやすくする
- 必要な情報だけを書く
- ドキュメントは人対人のコミュニケーションの一つという意識を持つ
良いドキュメントってなに？
ドキュメントを読み書きすることは、何か目的を達成するための手段です。
書き手にとっての目的：何かを説明したり、報告したり、意見を伝えたり
読み手にとっての目的：必要な情報を得ること
この書き手と読み手の双方の目的を達成できることがドキュメントの役割。
そして良いドキュメントとは次のように定義できます。
- 必要な情報を正しく得られる
- 効率よく理解できる
- ポジティブに受け止められる
必要な情報を正しく伝えるために気をつけること
ドキュメントでは読み手に誤解なく情報を伝える必要があります。
具体的には下記を意識します。
- 明確な文章で書く
- できるだけ具体的に書く
- 誤解なく読める文章で書く
例えば「簡単に」「速やかに」「早めに」などは読み手によって解釈に差が出るような表現になります。また、「設定を確認してください」など設定がどうなっていればいいかがわからない表現も疑問を感じさせてしまう危険があります。
そのため具体的な数字を使ったり、何をどうしてほしいかが伝わるような文章に置き換えるとよいです。
例えば下記のような置き換え：
このMTGは早めに終わる予定です
👇️
このMTGは約20分ほどで終わる予定です
具体的な数字を使うことで曖昧さを排除できています
メールの設定を確認してください
👇️
メールのサーバー設定が「xxx」となっていることを確認してください
確認してほしい具体的な内容や手順を詳しく示すことで読み手が「何をどうすればいいのか」がわかるようになりました。
効率よく理解してもらうために気をつけること
まず、書き手はドキュメントをすべて読んでもらえるだろうと思ってしまいますが、実際には部分的に必要なところしか読んでもらえない事が多いようです。
確かに考えてみると、ライブラリのドキュメントや社内マニュアルのドキュメントを読むとき、必要な情報がありそうなところにあたりをつけ部分的に読んでいることがあるのではないでしょうか。
見出しをざっと眺めて、今必要としてる情報がありそうな章だけ読んだり。
検索キーワードをいれてヒットしたものからあたりをつけて読んだり。
このように読み手には目的があり、その目的が達成できそうな部分のみを読んでいる事が多いわけです。
そのためドキュメントを書く時は「流し読みされることを前提にして、それでも必要な情報が伝わる」ように意識することが大切です。
特に読み手は他にやることがある中でドキュメントを読んでいることが多いのでドキュメントが「効率よく理解できる」状態にしてあると多くの人の時間が節約できます。
具体的には下記を意識します。
- 要点を先に言う
- 要点＋理由、説明、詳細のセットを心がける
- どこに何がかいてあるかわかりやすくする
- アウトラインを整理し、内容が予想できる見出しをつける
- 話の流れを整理し、理解しやすくする
- Aの話をしたあとにBの話、その後またAの話がでてくる、というような話がいったりきたりするような構造は読み手に負担がかかる
- 書く前に全体を整理し順序立てて伝える
- 簡潔で読みやすい文章を書く
- 一文一義（１つの文章に１つの意味）を心がける
- ひとつの文章に含める情報をなるべく減らそうと意識することが大切
- 必要な情報だけを書く
ポジティブに受け止められるよう気をつけること
ドキュメントでは情報を正しく効率的に伝えることを目指しますが読み手への心情を配慮することも大切です。
ドキュメントを書いて読んでもらうということは人対人のコミュニケーションの一つです。
例えばプロダクトに関わるメンバーが増えたとき、できることならそのメンバーに良い印象を持ってもらいたいはずです。
ポジティブに受け止められるようにするには文章を肯定形で書くと効果的です。
同じ意味を伝える文章でも否定形と肯定形では受ける印象がまったく違います。
例えば下記の２文は同じ意味ですが、肯定形のほうがポジティブな印象を受けます。
「◯◯日までは対応できません。」
👇️
「◯◯日以降でしたら対応できます。」
また、肯定形で表現できる場合は、なるべく肯定形を使ったほうが文の意味がはっきりします。
読み手の行動を促したいときは、してもらいたい行動を具体的に書くと意味が明確になります。
逆に禁止事項などはあえて否定形で書くと効果的です。
「◯◯というファイルは編集しないでください」などです。
さいごに
私自身、過去に素晴らしく整備されたドキュメントのおかげで作業がスムーズに進んだ経験があります。「これがあったおかげで助かった」と心底思いました。
ドキュメントは情報を伝えるだけでなく、読み手の行動を促したり、共通理解を深めたり、生産性を高めたり、未来の自分を救ったりするために重要なものだと感じています。
まだまだ試行錯誤中ですが、今回まとめたポイントを意識することで、より良いドキュメントを作れるようになりたいと思っています。