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

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

---

定義

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

目標

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

構成

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

編集

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

経験と練習

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

具体的なヒント

短い段落を使う

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

付録を活用する

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

編集の例

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

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

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

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

まとめ

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

[GN⁺]

Hacker Newsの意見

• 記事の中で特に印象的だった引用を2つ紹介している。1つ目はXのスクリーンショットにあった「書く過程でアイデアは10倍よくなる」という文句。2つ目は冒頭の「最も説得すべき重要な相手は著者自身だ」という言葉。業界で何年も働いていても、いまだにデザイン文書の必要性に反対する人がいるのは驚きだ。Leslie Lamportは「文章を書くことは、私たちの思考がどれほど粗いかを自然が教えてくれる方法だ」と言っていた。技術ライティングの力をもっと伸ばしたいなら、Write Like an Amazonian(https://medium.com/@apappascs/…) を勧める
  • 「形容詞をデータに変えろ」という助言が技術業界全体に広まったせいか、最近見る履歴書はどれも数値だらけで、かえって何を意味しているのか分かりづらいほどだ
• デザインレビュアーとして、すべての文書作成者が必ず腹落ちさせるべき点がある。「よい文書は問題とその思考モデルを読者に理解させ、何週間も考え抜いて生まれた解法が紹介されたときに自然に納得させられる」という部分だ。私が最も好きな引用は「もっと時間があれば、もっと短い手紙を書いただろう」だ。デザイン文書は複雑な内容を単純にしなければならず、開発者が経験した紆余曲折や失敗を何でもかんでも詰め込む場所ではないと思う。そうした内容にももちろん価値はあるが、別の文書や付録などにまとめるのがよい。前に進む道を簡潔に示す必要がある
  • 「より多くの時間、より短い手紙」という表現のほうが好みだ
  • いつも自分にこう問いかけている。「この話題で無用な論争は起きるか？」「その論争に価値はあるか？」目標は、新しい読者が無理なく議論に参加できるようにし、重要でない部分では論争が起きないようにすることだ
• Amazonの会議は、発表者が散文形式の文書を配るところから始まる。全員が静かに座って文書を読み、余白に赤ペンでメモや質問を書き込む。実際にAmazonで働いたことはないが、このやり方は驚くほど効果的で、実際にその経験を語る人は皆気に入っている。貴重な会議時間を全員で読書に使うのは非効率に見えるが、実際には事前に読んで準備してくれば、もっと短い会議にできるはずだ。リアルタイムで同時に読む方式では、読むのが遅い人を待つことになったり、文脈不足で理解度に差が出たりして、結局みんなが曖昧な時間を過ごすことになる。Googleでデザインレビューをすると、参加者の大半が準備なしで初見の文書を見ながら議論に加わる場面をよく見た。これはGoogleに強い文書文化がなく、チームリードやマネージャーも準備せずに来ることを暗黙に許していたからだと思う。会議前にきちんと読んでくる文化さえ定着すれば、会議時間はずっと効率的に使えるはずだ
  • 人々は会議前に読んでくれば会議時間は短くなると言うが、Amazonの慣行は、人は実際には事前に読んでこないという現実への対応だ。以前の関連記事によれば、事前に読んで準備する強い文化を作るのは事実上不可能だったという。参加者全員が直前の会議のせいで準備できず、その前にもまた別の会議があったからだ。理屈の上では会議数を減らせばいいという批判もできるが、実際には会議に価値があり、読む時間を含めても十分に意思決定が行われていたという。結局は結果に注目すべきで、実際Amazonではこの方式の利点が欠点を上回ると感じているようだ
  • 文書をいつ読むかがなぜ重要なのか疑問だ。もし時間がもっと必要なら、会議時間を延ばせばいい。欠点があるとすれば会議日程を組みにくいことだが、総所要時間は変わらないという意見だ
  • 全員の理解レベルがそろっていなかったり、誰かのコーナーケースを見落とすのではないかと心配したりすると、むしろもっと多くの時間が無駄になると思う
  • 実際に会議で扱われなければ何も起きない、という経験を語っている
• 明確さと編集に関する優れた助言が多い。弱点は、文書が承認された後にどう管理するかだ。管理がなければ「デザイン考古学」の状態へと劣化していく。数年前、Andrew Harmel-Lawは組織内でアーキテクチャ上の意思決定を効果的に記録する方法としてArchitecture Decision Records(ADRs)を提案しており、この方式は役に立つかもしれない。ADRはコードの横に置かれ（例: adr/001-use-postgres.md）、文脈と決定、そして状態を短く記録する。そのためPRごとに簡単にレビューでき、状況が変われば簡単に置き換えられるのが利点だ。元の意思決定の根拠も、数か月後でも検索できるようになる。[リンク: https://martinfowler.com/articles/…]
  • このやり方だと、Security、Privacy、Compliance など組織全体の委員会が、ADRを含むすべてのPRでレビュアーになるのか気になる。そうしたPRが90日以内にマージされるのか疑問だ
  • MF.com(https://thoughtworks.com/radar/techniques/…) のリンクはまだ全部読んでいないが、「Advice Process」は「みんなと話せ」で終わってしまう。「Managing」という肩書きを持つ人はこのあたりで興味を失いそうだ。本当の核心は「4つの支援要素」だが、ADRをもっと知ろうとして このリンク を開いたら、結局PDF(https://thoughtworks.com/content/dam/…) をダウンロードさせられた。そもそもADRが何なのか、定義をもっと明確に示してほしい
  • Session messengerは代表的な例だ。デザインとアーキテクチャの変更が非常に多く、どう動作するのかを正式に説明する権威ある情報がない。参考までに、セキュアメッセージングが必要なら普通にSignalを使えばいい
• 私の経験では、構成力と明確さが、SWエンジニアが文書作成能力を伸ばすうえで最大の障害だ。著者の「コードスパゲッティ」という比喩は、アイデアを整理する重要性を説明するよい例だと思う。私も以前、似た話を別の言い方で伝えようとしたことがあり、今後はこの比喩を使うつもりだ。以前、似たテーマでブログ記事を書いたことがあるが(https://ryanmadden.net/things-i-learned-at-google-design-docs/)、情報密度や実践の重要性など、共通点と会社ごとの差が興味深かった。「短い段落」という主張については少し違う考えだ。情報がよく磨かれてこそ短い段落が生まれるのであって、ただ改行するだけでは役に立たない。「Editing」の節のほうが、その根底にある考えをよりよく説明していると思う
• 私が使っている1つのプロセスがある。第1段階: 思いついたことを何でも文書に吐き出す（音声入力を使ってもよい）。第2段階: LLM（大規模言語モデル）に構造と流れを整えさせてみる。実際、この段階では結果を捨てることもあり、考えを練り続ける過程でもある。第3段階: LLMの結果を参考にしたり、まったく新しくアウトラインを組んだりして最初のドラフトを書く。第4段階: 単語を減らし、より簡単な言葉に置き換えるなどして、できるだけ簡潔にする。第5段階: 第4段階を繰り返す。LLMは、まとまりのない下書きを構造化する橋渡しの役をしてくれる。LLMの出力を捨てる覚悟も必要だ。少なくとも30%はいつでも削れる。削っても意味が失われないのを見るたびに驚かされる
  • 自分の文章を再編集する過程は、最初に書くことと同じくらい重要だと感じる。このとき、自分がどれだけ性急に結論を出していたか、何を考慮していなかったかが分かる。多くの人は、書くことを思考を集中させる道具として十分に評価していないように思う。コードも同じだ。単なるテンプレートを書く場合でさえ、テストコードを書いているうちにメインコードを改善するアイデアが浮かぶことが多い。だがLLMは、こうした質的な改善の機会を教えてはくれない
  • 拡張し、縮め、圧縮し、また拡張し、また圧縮する。その繰り返しだ。誰かが具体的な質問をすれば再び拡張し、最後にはLLMを使って気楽に楽しむための要約を作ることになる。私たちは本当に終わりのないジェットコースターに乗っているようなものだ
• もっと文章を書くべきだと思わされた。私が代表的な文書構成法だと考えているのは B.O.O. と Good Strategy/Bad Strategy だ。B.O.O. は Background, Objective, Overview の略で、どのような流れでここまで来たのか、何をどう変えようとしているのかを整理するものだ。Good Strategy/Bad Strategy は、診断、ガイドライン/前提条件/要件、そしてアクションで構成された本で、文書の組み立てという点ではB.O.O.に似ている。B.O.O. はGoogleや小規模な組織に向いており、Good Strategy/Bad Strategy ははるかに幅広い規模に適用できるが、筆力のある著者が必要だ
• 技術ライティングの授業を受けて、要点を明確に要約する力が大きく向上した。「赤ペンで削る」方式（文章を書き、線を引いて削り、また書き直す）に重点を置いていて、できるだけ少ない言葉で概念を伝える方法を重視している。このプロセスはいくつかの段階に分かれており、練習するほど簡単になる。こうした能力はチームメンバーにも共有しようとしているが、定期的に鍛えるべきスキルだということをいつも意識している
• こういう形で書かれた文書や、そうした文章文化そのものが本当に好きだ。ただし、このアプローチが逆効果になるケースも見てきた。このやり方は、なぜその結論に至ったのか、その理由と論理を説明する必要がある説得型の文書には非常に有効だ。しかし、常にそうした説得が必要とは限らない。ときには結論を先に直接書いたほうが、読者、特に書き手を信頼している読者にはむしろよい。多くの場合、読者は論理を追うことに疲れるより、まず要点を知りたがる。いったん結論を知ってから、ようやく細かな論理を追いたくなるのだ
  • 上に要約を置き、その下に詳細説明と根拠を続ける構成でも十分によい
• 自分しか読まないかもしれないデザイン文書を、自分で書くことがよくある。文書として書き残すだけでも強い力があると感じる。実際のサンプル文書があれば本当に助かると思う。自分の文書構成と、他の人たちの最終的な構成を比べてみたい