サクッと伝わるドキュメントを目指すためにエンジニアが意識していること

この記事は 株式会社ログラス Productチーム Advent Calendar 2024 のシリーズ 2、6日目 の記事です。

この記事は？

株式会社ログラスでクラウドインフラエンジニアをしている中井 (@elmodev09) です。

エンジニアとして働ていると、技術選定の調査結果をまとめたり、Design Docを書く等、ドキュメントを書く機会が多いのではないでしょうか？
ドキュメントは、不必要なディスカッションを減らすための非常に強力なツールです。
特に、抽象度が高いタスクにおいては、ドキュメントをうまく活用することで議論のポイントを明確化し、効率化を図ることができます。

個人的な話になりますが、これまでに書いたドキュメントについて、「分かりやすい」「読みやすい」と言っていただけることが多いです。
（もちろん、毎回そうではなく、分かりにくい場合もありますが）
私は口頭で全てを明確に説明するのが得意な方ではないため、思考を整理してドキュメントにまとめることで、なんとかエンジニアとしての業務をこなしています。

今回は、そんな私がドキュメントを作成する際に意識していることについて、お伝えできればと思います。
なお、私はテクニカルライティングの専門家ではないため、不備やツッコミどころがあるかもしれませんが、その点はどうか温かい目で見守っていただけると幸いです。
(むしろそういう意見があった場合は、後学のために教えていただけると嬉しいです！)

サクッと読めてざっくり理解してもらうようにする

いきなり結論です。
これを伝えたいがために今回のアドカレを書いたといっても、過言ではありません。

タイトルにも書いている通りですが、私がドキュメントを書く際に最も意識しているのは、「サクッと読めて、ざっくり理解してもらえるドキュメントになっているか？」 ということです。

書いたドキュメントは誰かしらにレビューをしてもらったり、読んでもらう必要があると思うのですが、内容が分かりにくい場合は、必要以上の時間が取られてしまいます。
そのため、ドキュメントはサクッと読めてざっくり理解してもらえるように工夫し、読み手の時間を最小限にする配慮と努力が必要だと考えています。

そのために具体的に私が行なっていることを次のセクションから紹介できればと思います。

理解しやすくするには、ドキュメント自体の設計が必要不可欠

サクッと読んで何となく理解してもらうためには、ドキュメント自体の設計が必要不可欠であると考えています。
ドキュメントの設計をするとは具体的に以下のことを行なっています。

1. 目的を明確にする
   • なぜこのドキュメントを書くのか、目的をはっきりさせる
2. 検討しないことを整理する
   • 検討しないことを整理し、前提条件として記載する
3. 読者を考える
   • 誰に読んでもらいたいのかを明確にする
4. セクション設計
   • 情報を整理するために、セクションを階層構造で構成する

一見、至極当たり前のように感じたり、どこかで見たことがありそうな内容ですが、それぞれについて詳しく説明していきたいと思います。

目的を明確にする

ドキュメントを書く際、「なぜこのドキュメントを書くのか」 と 「書いた結果、関係者がどのような状態になってほしいのか」 を明確にすることが重要だと考えています。

例えば、ある技術選定についてチームで意思決定したいため、マネージャーから「技術選定を行うための必要な材料を調べてまとめて欲しい」とふわっと依頼されたケースを考えてみます。

この場合、以下のように定義できます。

• なぜこのドキュメントを書くのか
  → 技術選定の意思決定をチームで行えるようにするため
• 書いた結果、関係者がどのような状態になってほしいのか
  → スムーズに意思決定を行うために、チームメンバー全員が必要な論点とその内容を全て理解できている状態

「チームメンバー全員が必要な論点とその内容を全て理解できている状態」を目指すためには、以下のことを考える必要がありそうです。

1. 意思決定を行う際に考慮すべき論点は何かを洗い出す必要がありそう
   (コスト、運用のしやすさ、チームメンバーが慣れているか、ライブラリの豊富さ等)
2. 考慮すべき論点をわかりやすく伝えるためにはどうすればいいかを考えないといけない
   (比較表を作ると、一箇所にまとまって理解されやすそうとか)

このようにドキュメントの目的を考えると、具体的にどのような情報を整理すべきかやどのようにまとめればいいかが明確になりやすくなります。
結果として、後述するセクション設計も行いやすくなります。

検討しないことを整理する

目的を明確にするをやることによって、そのドキュメントで書くべき内容がわかりやすくなりますが、それに加えて 「検討しないこと」 を明確にすることも重要であると考えています。
これは特に抽象的かつ複雑性の高い物事をまとめる際には、必ず実施したほうがいいと考えています。
自分はいつも以下のような感じでドキュメントで記載しています。

xxのことは、今後△△の状態になった場合に検討する必要があるかもしれないが、
ここまで考慮すると検討する事項が多くて進めづらくなるため、今回は一旦考慮しないようにする。

検討しないことを整理する目的は、関係者全員に対して、共通認識を持たせ、必要最低限の必要なディスカッションをだけを行うことができるようにするためです。
明確にしないままドキュメントを書くと、読み手の期待と書き手の意図がズレ、混乱を招きやすくなります。

例えば、技術選定のドキュメントで、対象外の論点とその理由を明確に記載しないと、読み手からすると、「なぜこの論点に触れていないのか」と疑問を持たれやすくなり、最悪の場合、手戻りになってしまいます。
(自分はこれを何回もやらかした経験があります…)

サクッと読めて理解してもらうためには、このような事態を防ぐべきです。
なので、ドキュメントを書く前に、「なにを検討しないか」 を明確にしておき、関係者全員で擦り合わせておけるとベターです。

読者を考える

次に、このドキュメントを誰が読むのかを具体的に考えます。
読者が誰かによって、説明すべき内容や情報の粒度が大きく変わるためです。

そのため、私は特に 「読み手がドキュメントの内容についてどの程度の知識を持っているか」 を考えるようにしています。
多数の読者が想定される場合は、その中でも最も知識量が低い読者を自分の頭の中で作り上げて、その人に対して、ドキュメントを書くようにしています。

こうして読者を具体的に想定しておくと、その人に沿って、どの部分を簡略にし、どの部分を丁寧に説明するかを考えやすくなります。

ドキュメントのセクション設計

ここまでできると、最後にドキュメントのセクションを作っていくことになります。
セクションはドキュメントの読みやすさの8割を占める(と勝手に自負している)非常に重要なポイントです。
読み手はセクションを見て、ドキュメントに書かかれていることを勝手にサマライズしてしまいます。
なので、セクション設計が良くないと、一気に読みにくいになってしまいます。
これを防ぐために、私は以下のことを意識しています。

• 上から順に読めるようにする
  (読み手にできるだけ行ったり来たりをさせないようにする)
• 階層構造を意識し、同じ階層はMECEに(漏れなくダブりなく)表現する

図で書いてみました。

こんな感じでセクションを設計できると、読み手にとってサッと理解できて、ざっくり理解できるドキュメントになりやすいのかなと考えています。

さらに読みやすくするために

ここまでで、ドキュメントに何を書いていくかが明確になり、おおまかなセクションまで作れました。

セクション設計だけでドキュメントの読みやすさの8割が決まると思っていますが、さらにさっと読めて、理解しやすいドキュメントを目指すために、私がよく使っているテクニック的なものを紹介できればと思います。

できるだけ図表を使う

ドキュメントを書く際は文章だけの説明は避けて、できるだけ図表を使うべきです。

これも当たり前ではあるのですが、人間は文字を読むよりも、図で直感的に表現してもらった方が理解のスピードが明らかに早いです。
(とはいえ私はこれをわかっていても、図を作るのは時間がかかるため、サボりがちです…)
図表を使うことで、1セクションあたりの文字数を減らすことができるのもメリットです。

例えば、「ユーザーがフォームを送信し、データがデータベースに保存されるまでのフロー」を文章で書く場合とシーケンス図で書く場合で比較してみたいと思います。
(余談ですが、↑の例はChatGPTに出してもらいました。すごい！)

1. 文章で書く場合
以下のような感じになるかなと思います。

1. ユーザーがフォームを送信すると、フロントエンドがサーバーにHTTP POSTリクエストを送信します。
2. サーバーはリクエスト内容を検証し、問題がなければデータをデータベースに保存します。
3. サーバーは成功メッセージを返し、フロントエンドは画面にメッセージを表示します。
   - サーバの処理中でエラーが発生した場合は、フロントエンドにエラーを返し、エラー画面を表示をだす

これぐらいの文章だと、サクッと読めますが、フローが複雑になればなるほど、誰が参加していることが把握しづらく、その参加者同士の関係が読みづらくなりそうです。

2. シーケンス図で書く場合

シーケンス図を書くとそのフローの参加者が一気にわかりやすくなります。
書いている文章も端的になり、読みやすくなります。

↑はあくまで一例ですが、図表を使うことで直感的に理解しやすいドキュメントになりやすいです。
他にも、検討項目の比較はテーブルを使う等、様々なテクニックがありますがここでは割愛させていただきます。

要約をドキュメントの先頭に配置する

ドキュメントをすべて書き終えたら、要約を作成し、文章の先頭に置くことをお勧めします。
これをドキュメントの冒頭に配置することで、読み手にとってより理解しやすい構成になると考えています。
要約が最初にあることで、読み手は「要約を読んでから、確認したい部分だけをセクションごとに見直す」という効率的な読み方ができるようになります。

これにより、ドキュメントを読む時間を短縮でき、特に忙しい関係者にとって助けになります。
（もちろん、セクション設計や内容の整理など、ドキュメント全体が分かりやすいことが前提です。）

まとめ

いかがでしたでしょうか？

今回はドキュメントを書く際に私が意識していることを、ざっと書いてみました。
結論、ドキュメントの読みやすさは「相手の時間を取らせないために努力した量」で決まるかなと考えています。
なので、ドキュメンテーションは、割と意識を変えるだけですぐに向上させることができる能力かなと考えています。

私は今回書いたことを基本方針としてドキュメントを書いていますが、もちろんドキュメントの種類によっては、守れない場合もあるので、その時は臨機応変に対応しています。

書いている最中に思ったのは、この手のドキュメント系の記事は結構調べたら出てくるし、大体同じ内容が記載されているなということでした。
ただ、自分がドキュメントを書くときに意識していることを改めて言語化できたのはいい機会になったのではないかと考えています。

私が意識していることが読者のみなさまのなにかしらの参考になれば、嬉しい限りです！