こんにちは。壮（@sew_sou19）と申します。
メガベンチャー企業でエンジニアとして働いています。

エンジニアにジョブチェンジした当初は、ドキュメントの書き方なんてこれっぽっちも分かりませんでした。読みやすいドキュメントを書くことが本当に苦痛だったのですが、考えて、試行錯誤し続けた結果、以下のような評価を得るに至りました。

そこでこのnoteでは、僕がドキュメントを作成するときに、特に意識して実践している7つのことを書きます。（本当は2万文字ほどお伝えしたいことがあるのですが、さすがに短時間で読みきれないので、別のnoteに任せたいと思います。）

たった7つなので、読んだらすぐに実践できると思います。

一方で「なぜ読みやすいか／なぜ読みにくいか」など、順序立った説明は一切行っておらず、個別かつ具体的なポイントにのみフォーカスしています。

読みやすいドキュメントを書くことについて、体系的に知りたい方はこちらをご参照ください。

では早速書いていきます。

1. 書くまえに、ドキュメントの目的を明確に定義する

読みやすいドキュメントの大半の要素は、ドキュメントを書き始める前に決まると思っています。「何のために・誰のために・何を書くのか、を明確に定めること」が、読みやすいドキュメントを作成する上で重要です。

そこでまずは「何のために、何を伝えるドキュメントなのか」を明確に定義します。いきなり書き始めるのではなく、ほんの数十秒でもいいので考えてみてください。

• 目的が定まっていないドキュメントは「ドキュメント」でない（メモと同義）

• 目的を一言で定義できるのが理想

• 定めた目的をドキュメントの「概要」として書く

一つのドキュメントに対して目的は一つに絞ります。目的が複数あるドキュメントは読み手に高い負荷をかけてしまいます（これって結局何について書かれたドキュメントなんだっけ？と余計な思考をさせてしまう）。

• 主目的が複数存在する場合はドキュメントを分けるべき

• 主目的に関連する副目的ならOK

2. 書くまえに、筋道が立っているかを強く意識する

読み手の理解を促進するためには、階段を一段ずつ上がっていくように説明するのが効果的です。

• 読み手が知っている/理解しやすいことから順を追って説明する

  • 読み手は、階段を一段ずつ上がっていくように説明されると理解しやすい

  • 反対に、知らないことが一段目にあるとつまづいて理解が難しくなる

  • 読み手が階段の一段目を登れるかに配慮する

この「読み手が知っている/理解しやすいことから順を追って」というのが重要であり、筋道を立てる際のコツでもあります。

■悪い例
いきなり具体的な話をしてしまっています。

「認知特性」や「チャンキング」という聞き馴染みのないワードの説明をせずに先に進んでいるため、読み手は「認知特性？認知における特性？どういうこと？」「チャンキングってなんだ…？」と、伝えたいこととは別のことに意識が向いてしまいかねません。

最後の方でワードの説明は行なっているものの、意味を理解した上で再度頭から読まないと文章の全体像を捉えることは難しいです。そのため、読み手が理解することに時間を要してしまいます。

■良い例
読み手が知っていることを徐々に広げる流れで書かれています。

仮に読み手が知らないであろうワードが出てきた場合は、都度説明を行なっているため、文章を読んで内容を理解することに集中できます。そのため読み直しの必要がなく、短時間で認知特性の有効性を理解することができます。

このように、筋道を立てるか否かでドキュメントの読みやすさに大きな違いがあります。立て方の例は以下です。

• 全体から部分への展開

• 概要から詳細への展開

• 既知から未知への展開

• まず重要を説明

• まず相手が知りたいことを説明

• 作業や手順を流れに沿って説明

3. 書くときに、読み手視点を強く意識する

「自分がもし読み手だったらどう思うか？」という視点を忘れずに書く必要があります。

• 読み手は書き手ではない

  • 書き手が当たり前と思っていることは、読み手にとっては当たり前ではないことが多い

  • 読み手とする具体的な人を設定するとイメージしやすい

  • 「Aさんならこの説明が必要そうだな」

• 読み手に期待しすぎない

  • 読解能力が高くて行間を読んでくれる人とは期待しない

  • 全く前提知識のない第三者でも容易に理解できるように書く

  • 一意に受け取ることができる表現を用いる

• 読み手を置き去りにしない

  • 書き手が書きたいことを書くのではなく、読み手が読みたいこと（＝知りたいこと）を書く

  • 読み手が期待していることを想像する

  • 読み手が知らないことを前提に話を進めない

4. 書いたあとに、自身で推敲する

自身で書いた文章を読み直すことで、客観的に気付くことが多く、ドキュメントを読みやすくできます。

一般的な人間の能力は、書く力より読む力の方が優れていると言われています。

書くときには違和感がなかったとしても、読み直す際には「なぜこんな駄文を！？」と思った経験をお持ちの方も多いと思います。

そのくらい能力差があるので自身で推敲するだけで効果は高いのですが、意外とやっていない人が多いです。

推敲する際は、以下をチェックリストとして活用してみてください。

5. ドキュメントの冒頭に要点をまとめる

冒頭に要点をまとめることで、読みやすいドキュメントに近付きます。

「このドキュメントはAについて書かれたものである」と、たった1行でも構いません。

この1行によって、読み手は、ドキュメントを読む準備を整えることができます。準備が整うことでそのあとの詳細な話を理解しやすくなるため、やらない手はありません。

以下は要点をまとめる際のポイントです。

• タイトル：ドキュメントの内容を明示的に示す

  • 「〜について」のような曖昧なものはNG

  • あとから検索されやすいものにする

  • ドキュメントの目的を端的に表すものにする

• 概要：「これは何のドキュメントであるか」を端的に示す

  • 1行でもいいのでドキュメントについての説明をする

  • 概要だけでドキュメントの全体像が把握できるのが理想

  • 長すぎると本質から外れるので適度に

6. 一文一義・一文50文字以内で書く

簡潔に書くことによって、ドキュメントの効率性と快適性を高めることができます。

• 一文一義で書く

一文で多くのことを伝えようと、一文多義にしてしまうと、何を伝えたいのかが分かりにくくなってしまいます。

• 文の長さは50文字まで

一度書いた後に読み直すと、もっとシンプルに書ける場合が意外と多くあります。50文字を超える冗長な文は、50文字以内に収められないか推敲してみるのがおすすめです。

7. 表や図を用いる

表や図を適宜用いることで、ドキュメントの効率性と快適性を飛躍的に高めることができます。「色々と工夫しているのに結局伝わっていない…」という場合は、表や図を用いることで解決に向かうことが多いです。

「適宜」の具体例を挙げます。

• 一覧（リスト）を示したいとき　→　表を用いる

• 比較を示したいとき　→　表を用いる

• 時系列で物事の流れを示したいとき　→　表を用いる

• 見た目に関わる表現をするとき　→　図解を用いる

• 同じ粒度の項目　→　リストがおすすめ

• データや処理の流れを伝えるとき　→　UMLがおすすめ

「UML」とは、Unified Modeling Languageの略語です。日本語では「統一モデリング言語」と呼ばれています。噛み砕けば、クラス図やシーケンス図などの総称です。

このように表や図を適宜用いることで、書き手が考えている複雑なことを明確に表現できます。読み手は視覚的に想像ができるため、内容の理解も早くなります。

以上です。

どういうドキュメントが読みやすいのか、それはなぜなのか、といった体系立った説明は一切省き、ポイントを絞って書いてきました。

短時間で読み切ることに注力して書いたので「さすがにもう少し周辺情報を含めて知りたい」という方は、以下の無料部分を読んでいただけると嬉しいです（半分以上無料で読めます）。

感想等はTwitterでいただけたら泣きます。

ではまた。