皆さん、こんにちは。王です。
私はこの本を読んで、ドキュメント作成についての考え方が変わりました。
上司からはよく「説明力が不足している」と言われます。いつもコードの流れで機能の説明をしてしまうため、相手に内容が伝わりにくく、困っていました。また、私自身もコードを書くのは好きですが、文章を書くのは苦手です。ドキュメントを書き始めても「何を」「どこに」書けばいいか分からず、時間がかかっていました。そして、できあがったドキュメントは、他の人から「論理が分かりにくい」「話の流れがバラバラだ」と言われることが多かったです。
そのため、これらの悩みを解決したくて、この本を読んで勉強しようと思ったのです。
ドキュメントを速く、正確に、わかりやすく書くために必要なのは「まとまった時間」ではなく、「正しい手順を知っているかどうか」です。そして、ドキュメント作成は「設計」であるという核心的な考え方を教えてくれました。
１.ドキュメントは「設計」から始める
プログラミングでは、要件定義の後に「設計」をしてから「実装」をします。ドキュメントも同じです。
多くのエンジニアは、いきなり文章を書き始めてしまいますが、これが失敗の原因です。この本は、まず「読み手とテーマの選定」をして、次に「構成の設計」をして、最後に「執筆」をする、という手順の重要性を強調しています。
適切な設計をすることで、読み手は必要な情報を効率良く得ることができ、書き手は効率良く作業を終えることができます。
２.思考を整理する「Why/What/How」フレームワーク
ドキュメントの設計図を作るために、この本は強力なフレームワークを提案しています。それが、テーマを3つの要素に分解する「Why/What/How」です。
- Why（なぜ）： なぜそれが必要ですか？（目的、背景）
- What（何を）： 何をするか、何が目標か？（結論、結果）
- How（どうやって）： どうやって実現しますか？（手段、手順）
このフレームワークを使ってテーマを整理すると、頭の中の複雑な情報が整理されて、ドキュメントの構成（アウトライン）が明確になります。アウトラインは、読み手が「どこに何が書いてあるか」を一目で判断するためのナビゲーターです。
【具体的なドキュメントへの応用例】
仕様書作成のポイント：
仕様書を書くとき、開発者がスムーズに作業できるように、情報を分解し整理することが大切です。まずプロダクトの全体像を説明し、それから機能の構成要素（機能1、機能2、画面など）で分解して説明を展開していきます。こうすることで、開発者は全体を理解しながら、各機能を開発できます。
報告書作成のポイント：
報告書では、Why→What→Howの順番で情報を提供するのが基本です。特に、結果（What）から得られた「考察」をしっかり書くことが、報告書の価値を高めます。
３.わかりやすい文章の作り方
設計ができたら、最後に文章の執筆です。この本は、わかりやすい文章を作るための「パラグラフ（段落）」の考え方を教えてくれます。
1パラグラフ＝1つの話題： 1つの段落では、「言いたいこと（中心文）」を一つだけ書きます。
展開のパターン：「言いたいこと」をまず書いてから、その下に「理由を挙げる」「具体例を挙げる」「詳細を述べる」といったパターンで文章を展開します。
最初にパラグラフごとの「言いたいこと」だけを1文で書き、その後に理由などを書き足していく、という手順（ステップ）を踏むことで、文章が論理的になり、話の流れがブレなくなります。
結論：ドキュメントスキルは一生の武器
この本は、ドキュメント作成を「感覚」や「才能」ではなく、「手順」と「ロジック」で実現できるスキルに変えてくれました。
私はこの本を読んで、ドキュメント作成に対する不安がなくなりました。ドキュメント作成スキルは、私たちが複雑なアイデアを整理し、他の人に正確に伝えるための、エンジニアとしての強力な武器になります。ドキュメントに苦手意識があるエンジニアに、心からおすすめしたい一冊です。
（参考情報）
この本と、仲田尚央さんの素晴らしいPPT資料（内容が詳しく、論理的なので、本と一緒に読むのに最適です。PPTは無料で公開されていたので、リンクを添付します：
https://speakerdeck.com/naohiro_nakata/basics-of-documentation-for-engineers