あらすじ
「え、僕の設計書、ダメでしたか…？」
入社2年目のユウタが少し落ち込んでいる。機能の設計書を仕上げたものの、先輩から返ってきたのは「ユウタの頭の中では完璧なんだろうけど、後から読む人が分かるかな？」の一言。
“ちゃんと書いたはずなのに！”とモヤモヤするユウタに、先輩が「伝わるドキュメントにはコツがあるんだよ」と笑顔で助言をくれる。
ユウタ
「先輩、昨日の設計書レビュー…けっこう刺さりました。“後から読む人が分かるかな？”って、そんなに分かりにくかったですか？」
先輩
「うん、内容はバッチリだったよ。でもね、“分かりやすさ”って、実は正しさとは別のスキルなんだ。」
ユウタ
「別のスキル…ですか？」
先輩
「そう。ドキュメントって、自分の頭の整理じゃなくて、“他の人の理解を助けるためのもの”。つまり――」
ユウタ＆先輩（ハモる）
「“他者のための設計書！”」
ユウタ
「…あ、先輩に合わせちゃいました（笑）。」
先輩
「いいね、ノリが大事。今日は“伝わるドキュメントの3つのコツ”を伝授しよう。」
メソッド①：読者ペルソナ設定 ― “誰に向けて書くか”を考える！
先輩
「まずは、“このドキュメント、誰が読むの？”って考えることから。
たとえば、新しく入った運用担当者が読むなら、何が知りたいと思う？」
ユウタ
「えっと…システムの全体構成とか、処理の流れですかね。」
先輩
「その通り。だから、細かいコードよりも“全体がどう動くか”を中心に説明する。
逆に、後輩エンジニアが読むなら、“注意すべき設定”とか“ハマりポイント”を詳しく書くと親切なんだ。」
ユウタ
「なるほど、読む人によって“親切の形”が違うんですね。」
先輩
「うまいこと言うね。要するに、“相手の知りたいことを逆算する”のがコツ。ペルソナを決めると、内容が自然に整理されるんだ。」
ユウタ
「なるほど、まるで“プレゼント選び”みたいですね。相手のことを想像する！」
先輩
「おっ、それいい例えだね。読む人が“欲しい情報”を贈る気持ちで書こう。」
メソッド②：結論ファースト（PREP法） ― “最初に答えを出す”勇気！
ユウタ
「2つ目のコツはなんですか？」
先輩
「“結論ファースト”だ。PREP法って聞いたことある？」
ユウタ
「大学のゼミで聞いたような…Pがいっぱいあるやつですよね。」
先輩
「そうそう、Point（結論）→Reason（理由）→Example（具体例）→Point（結論）の順番。
たとえば設計書で“例外処理”について書くとき――」
Point（結論）：この機能では全ての例外を共通エラーロガーで処理します。
Reason（理由）：障害発生時の原因特定をスムーズにするためです。
Example（具体例）：API接続エラーはErrorLogger.log()で出力します。
Point（再び結論）：これにより、保守性が高まり、トラブル対応がスピーディーになります。
ユウタ
「おお、分かりやすい！最初に答えを見せてくれると、安心して読めますね。」
先輩
「そう。読む人に“いま何の話か”を早く理解してもらうのがポイント。
“結論は最初と最後で二度言う”――これ、伝わる文章の黄金ルールだよ。」
ユウタ
「了解です！結論はサンドイッチで！」
先輩
「いいね。言葉のセンスも育ってきたな（笑）。」
メソッド③：図解とテキストの使い分け ― “見て分かる”は最強！
ユウタ：「3つ目はやっぱり“図”ですか？」
先輩
「その通り。エンジニアは図解に救われる生き物だからね（笑）。
全体の流れや構造は図で、細かい設定値や例外条件はテキストで補足。
つまり、“大きくつかんで、細かく確認”の二段構えだ。」
ユウタ
「あぁ～、まさに“地図とガイドブック”の関係ですね。」
先輩
「それもいい例えだね！
文章だけの設計書って、迷路みたいになるでしょ？だから図を入れて、読む人の頭に“地図”を描かせるんだ。」
ユウタ
「たしかに！図があると安心します。読んでる途中で迷子にならない。」
先輩
「そうそう。“視覚で理解、文字で納得”が最強の組み合わせなんだよ。」
ユウタ
「いやー、今日も学びが多いです。なんか、設計書がちょっと楽しくなってきました！」
先輩
「いいね、その調子。“書く”ってのは、相手への思いやりを形にする作業だからね。」
ユウタ
「思いやりのドキュメントか…かっこいい！
次こそ、“読んで気持ちいい設計書”にしてみせます！」
先輩
「おっ、頼もしい！ドキュメントもユウタも、どんどん“伝わる”ようになってるね。」
🔍 応用ヒント：実務で活かすポイント
- ・ドキュメントの冒頭に「この資料は誰向けか（例：運用担当者向け）」を明記すると親切！
・書いた後は“他チームの人”に読んでもらい、理解できるかテストしてみよう。
・図には「タイトル」と「意図」を添えて、“何を伝えるための図か”をはっきりさせる。
・一文は短く、主語をはっきり！「読むストレスゼロ」を目指そう。
・“未来の自分”も他人。数ヶ月後の自分が読んで分かるかを想像して書こう。
先輩のひとこと
「伝わる設計書は、最高のチームプレー。書き手の“気配り”が、プロジェクトを前に進めるんだよ。」