読みやすいドキュメントを書くために今日からできる7つのこと
こんにちは。壮（@sew_sou19）と申します。
メガベンチャー企業でエンジニアとして働いています。
エンジニアにジョブチェンジした当初は、ドキュメントの書き方なんてこれっぽっちも分かりませんでした。読みやすいドキュメントを書くことが本当に苦痛だったのですが、考えて、試行錯誤し続けた結果、以下のような評価を得るに至りました。
リーダーから「君は情報の整理が上手でドキュメントが本当に読みやすい。チーム全体の能力向上に繋げたいからドキュメント書く際のポイント共有してほしい」と言われたので、意識していることを言語化しつつテクニカルライティングの本でインプットしてるけど、学びが多い。ついでにnoteにもまとめてる
— 壮 (@sew_sou19) November 28, 2022
そこでこのnoteでは、僕がドキュメントを作成するときに、特に意識して実践している7つのことを書きます。（本当は2万文字ほどお伝えしたいことがあるのですが、さすがに短時間で読みきれないので、別のnoteに任せたいと思います。）
たった7つなので、読んだらすぐに実践できると思います。
一方で「なぜ読みやすいか／なぜ読みにくいか」など、順序立った説明は一切行っておらず、個別かつ具体的なポイントにのみフォーカスしています。
読みやすいドキュメントを書くことについて、体系的に知りたい方はこちらをご参照ください。
では早速書いていきます。
2023/02/05：一部内容を変更しました。
1. 書くまえに、ドキュメントの目的を明確に定義する
読みやすいドキュメントの大半の要素は、ドキュメントを書き始める前に決まると思っています。「何のために・誰のために・何を書くのか、を明確に定めること」が、読みやすいドキュメントを作成する上で重要です。
そこでまずは「何のために、何を伝えるドキュメントなのか」を明確に定義します。いきなり書き始めるのではなく、ほんの数十秒でもいいので考えてみてください。
目的が定まっていないドキュメントは「ドキュメント」でない（メモと同義）
目的を一言で定義できるのが理想
定めた目的をドキュメントの「概要」として書く
一つのドキュメントに対して目的は一つに絞ります。目的が複数あるドキュメントは読み手に高い負荷をかけてしまいます（これって結局何について書かれたドキュメントなんだっけ？と余計な思考をさせてしまう）。
主目的が複数存在する場合はドキュメントを分けるべき
主目的に関連する副目的ならOK
（×）このドキュメントは、案件の概要と仕様をまとめつつ、進行の方法について書くことが目的だ
（○）このドキュメントは、機能の仕様を、後からジョインしてくる人も理解できるように整理するのが目的だ
2. 書くまえに、筋道が立っているかを強く意識する
読み手の理解を促進するためには、階段を一段ずつ上がっていくように説明するのが効果的です。
読み手が知っている/理解しやすいことから順を追って説明する
読み手は、階段を一段ずつ上がっていくように説明されると理解しやすい
反対に、知らないことが一段目にあるとつまづいて理解が難しくなる
読み手が階段の一段目を登れるかに配慮する
この「読み手が知っている/理解しやすいことから順を追って」というのが重要であり、筋道を立てる際のコツでもあります。
▼悪い例
認知特性に基づいた「チャンキング」という作業を行うといい。これによって、短期記憶の特性をうまく利用して理解を促進させることができる。
「チャンキング」を行わないと読み手の負荷を高めることになり、ドキュメントを読むこと自体をやめてしまう蓋然性を高める。なぜなら人間は、1つの概念を理解するのに必要な要素が複数あったり、粒度の細かな項目が数多くあったりすると理解が難しくなるからである。
ちなみに、認知特性とは人間の認知心理学に基づいた「認知の仕方」のことである。ここから「どのようなドキュメントだと人間は受け入れやすいか」ということが分かる。
人間の短期記憶は20秒ほどしかもたなかったり、一度に保持できるのは約7項目までなので、似たものをまとまりとして捉えることで、全体の理解を促進できる。（「チャンキング」は、似ている要素を集めてまとまりを作ることである）
▼良い例
人間の「認知特性」を利用することで、さらに読みやすいドキュメントにすることができる。
認知特性とは人間の認知心理学に基づいた「認知の仕方」のことである。ここから「どのようなドキュメントだと人間は受け入れやすいか」ということが分かる。
例として、似たものをまとまりとして捉えることで全体の理解が進むことを挙げる。
人間には、短期記憶は20秒ほどしかもたなかったり、一度に保持できるのは約7項目までという特性がある。そのため、1つの概念を理解するのに必要な要素が複数あったり、粒度の細かな項目が数多くあったりすると理解が難しくなる。
そのため、似ている要素を集めてまとまりを作る「チャンキング」を行うことで、さらに読みやすいドキュメントを書くことができる。
■悪い例
いきなり具体的な話をしてしまっています。
「認知特性」や「チャンキング」という聞き馴染みのないワードの説明をせずに先に進んでいるため、読み手は「認知特性？認知における特性？どういうこと？」「チャンキングってなんだ…？」と、伝えたいこととは別のことに意識が向いてしまいかねません。
最後の方でワードの説明は行なっているものの、意味を理解した上で再度頭から読まないと文章の全体像を捉えることは難しいです。そのため、読み手が理解することに時間を要してしまいます。
■良い例
読み手が知っていることを徐々に広げる流れで書かれています。
仮に読み手が知らないであろうワードが出てきた場合は、都度説明を行なっているため、文章を読んで内容を理解することに集中できます。そのため読み直しの必要がなく、短時間で認知特性の有効性を理解することができます。
このように、筋道を立てるか否かでドキュメントの読みやすさに大きな違いがあります。立て方の例は以下です。
全体から部分への展開
概要から詳細への展開
既知から未知への展開
まず重要を説明
まず相手が知りたいことを説明
作業や手順を流れに沿って説明
3. 書くときに、読み手視点を強く意識する
「自分がもし読み手だったらどう思うか？」という視点を忘れずに書く必要があります。
読み手は書き手ではない
書き手が当たり前と思っていることは、読み手にとっては当たり前ではないことが多い
読み手とする具体的な人を設定するとイメージしやすい
「Aさんならこの説明が必要そうだな」
読み手に期待しすぎない
読解能力が高くて行間を読んでくれる人とは期待しない
全く前提知識のない第三者でも容易に理解できるように書く
一意に受け取ることができる表現を用いる
読み手を置き去りにしない
書き手が書きたいことを書くのではなく、読み手が読みたいこと（＝知りたいこと）を書く
読み手が期待していることを想像する
読み手が知らないことを前提に話を進めない
4. 書いたあとに、自身で推敲する
自身で書いた文章を読み直すことで、客観的に気付くことが多く、ドキュメントを読みやすくできます。
一般的な人間の能力は、書く力より読む力の方が優れていると言われています。
書くときには違和感がなかったとしても、読み直す際には「なぜこんな駄文を！？」と思った経験をお持ちの方も多いと思います。
そのくらい能力差があるので自身で推敲するだけで効果は高いのですが、意外とやっていない人が多いです。
推敲する際は、以下をチェックリストとして活用してみてください。
- タイトルから文章の目的が分かる
- 全体の構成がロジカルに組み立てられている
- 見出しから内容が分かる
- 文と文とのつながりがある
- 必要な情報の抜け漏れがない
- 不要な情報が書かれていない
- 1文が長すぎない
- 表記の揺れがない
- 固有名詞の誤りがない
- 誤字脱字がない
5. ドキュメントの冒頭に要点をまとめる
冒頭に要点をまとめることで、読みやすいドキュメントに近付きます。
「このドキュメントはAについて書かれたものである」と、たった1行でも構いません。
この1行によって、読み手は、ドキュメントを読む準備を整えることができます。準備が整うことでそのあとの詳細な話を理解しやすくなるため、やらない手はありません。
以下は要点をまとめる際のポイントです。
タイトル：ドキュメントの内容を明示的に示す
「〜について」のような曖昧なものはNG
あとから検索されやすいものにする
ドキュメントの目的を端的に表すものにする
概要：「これは何のドキュメントであるか」を端的に示す
1行でもいいのでドキュメントについての説明をする
概要だけでドキュメントの全体像が把握できるのが理想
長すぎると本質から外れるので適度に
6. 一文一義・一文50文字以内で書く
簡潔に書くことによって、ドキュメントの効率性と快適性を高めることができます。
一文一義で書く
（×）APIキーはAPI提供者が独自に発行している認証情報で、不特定多数のユーザーからの接続を防ぐために有効だが、APIキーは発行者が任意に決めて問題ない。
（○）APIキーはAPI提供者が独自に発行している認証情報である。不特定多数のユーザーからの接続を防ぐために有効。APIキーは発行者が任意に決めて問題ない。
一文で多くのことを伝えようと、一文多義にしてしまうと、何を伝えたいのかが分かりにくくなってしまいます。
文の長さは50文字まで
（×）SSRはサーバーサイドでレンダリングしたHTMLを受け取るため、Googleのクローラが特に問題なく読み取ることができるがその一方で、CSRではSEO的に不利になるケースが存在するため、使う場合には注意が必要だが、速度面のメリットなどがあるので、可能な限りCSRに基づいた実装を行う方針とする。
（○）SEOの考慮が必要ない機能に関しては、CSRに基づいた実装を行う方針とする。
一度書いた後に読み直すと、もっとシンプルに書ける場合が意外と多くあります。50文字を超える冗長な文は、50文字以内に収められないか推敲してみるのがおすすめです。
7. 表や図を用いる
表や図を適宜用いることで、ドキュメントの効率性と快適性を飛躍的に高めることができます。「色々と工夫しているのに結局伝わっていない…」という場合は、表や図を用いることで解決に向かうことが多いです。
「適宜」の具体例を挙げます。
一覧（リスト）を示したいとき → 表を用いる
比較を示したいとき → 表を用いる
時系列で物事の流れを示したいとき → 表を用いる
見た目に関わる表現をするとき → 図解を用いる
同じ粒度の項目 → リストがおすすめ
データや処理の流れを伝えるとき → UMLがおすすめ
「UML」とは、Unified Modeling Languageの略語です。日本語では「統一モデリング言語」と呼ばれています。噛み砕けば、クラス図やシーケンス図などの総称です。
このように表や図を適宜用いることで、書き手が考えている複雑なことを明確に表現できます。読み手は視覚的に想像ができるため、内容の理解も早くなります。
以上です。
どういうドキュメントが読みやすいのか、それはなぜなのか、といった体系立った説明は一切省き、ポイントを絞って書いてきました。
短時間で読み切ることに注力して書いたので「さすがにもう少し周辺情報を含めて知りたい」という方は、以下の無料部分を読んでいただけると嬉しいです（半分以上無料で読めます）。
感想等はTwitterでいただけたら泣きます。
ではまた。
自身のキャリアで得た知見について言語化しています。執筆活動の励みになります！