よい設計ドキュメントの書き方

• 設計ドキュメントは、システムの実装戦略・制約事項・トレードオフを整理した技術レポートである
• 設計ドキュメントは、その設計が状況に適していることを読者に納得してもらうための役割を持つ
• ドキュメントの構成が重要であり、論理的な流れによって読者が内容に驚かないようにする必要がある
• 編集によって不要な言葉を減らし、読者の集中力という資源を節約することが必要である
• 短い段落と付録の活用、練習を通じた文書作成能力の向上が重要である

---

定義

• 設計ドキュメントは、システム実装戦略をトレードオフと制約条件の文脈で整理した技術レポートである

目標

• 設計ドキュメントは、数学における証明が定理を納得させるのと同じように、その設計が最適であることを読者に説得することを目的とする
• 設計プロセスでは、書くこと自体が思考の厳密さを高める
• 設計ドキュメントを書くことで、漠然とした考えを具体的な思考へと変えられる

構成

• よい設計ドキュメントの構成は、コードの整理と同じくらい重要である
• 初心者がコードを書くように、多くの人は**「スパゲッティ設計ドキュメント」**を書いてしまう傾向がある
• 論理的な順序なしに文を並べると、読者は文脈を追いにくくなり、混乱する
• 優れたドキュメントは、読者が驚かないように流れが自然でなければならず、各文は前の内容を土台に当然のようにつながるべきである
• 読者の思考状態を把握し、段階的に新しい状態へ導くことが目標である
• 想定される異議は事前に解消すべきであり、読者が反論を出す前に説明しておく必要がある

編集

• 内容をうまく構成した後は、**不要な言葉を削る（編集する）**段階が重要である
• 読者の集中力は限られた資源であり、不要な情報は思い切って削除する必要がある
• 下書きでは、意味の薄い表現をおよそ30%削減できる
• 他人の文書を編集しながら批判的な視点を養えば、自分の文章も効率的に磨ける
• **短いツイート（280字制限）**で練習することも、思考の単純化と圧縮力の向上に役立つ

経験と練習

• 反復練習ほど実力を伸ばす近道はない
• Amazonでのドキュメント中心の文化の経験は、文書作成能力の向上に大いに役立った
• 重要な会議では、1〜6ページ規模の設計ドキュメントを配布した後、全員が静かに読み、余白に意見を書き込む方式を用いる
• フィードバックを受けながら、文章力を実質的に高められる

具体的なヒント

短い段落を使う

• 設計ドキュメントは、連続した簡潔な bullet pointで流れを作るべきである
• 各bullet point（観察、アイデア、問題点、改善など）は、一つの概念に集中した短い段落で構成する
• 各段落は一文で要約できるほど明確であるべきであり、これによって読者の短期記憶の資源を節約できる

付録を活用する

• 複雑な計算やシミュレーション結果は、本文ではなく付録に詳しく整理し、本文では簡単な脚注の形で触れる
• 本文の主要な結論を理解するうえで付録は必須ではなく、気になる読者が参照できるよう提供する

編集の例

• （編集前、冗長な段落）:

  各bullet pointはドキュメント内で独立した段落であるべきだ。各段落は一文で要約可能でなければならない。実際に一文である必要はなく、概念を説明するために追加の説明が入ることはある。しかし読者が読み終えた後には、一文で要約できる状態でなければならない。

• （編集後、簡潔化した段落）:

  各bullet pointは一つの段落として、一文で要約できるべきである。実際に一文である必要はなく、必要であれば補足説明を加えてよい。しかし読み終えた後には、一文に圧縮できる状態であるべきだ。

まとめ

• 設計ドキュメントは、思考の厳密さ、論理的な流れ、読者中心の編集、そして反復練習を通じて能力を伸ばせる重要なプロセスである