優れた設計ドキュメントは、数年分の開発時間を節約する
How to Write an Effective Software Design Document
GoogleやMicrosoftで設計ドキュメントを書いてきた著者が、効果的な設計ドキュメントの作り方を解説する。複数人での作業、3か月以上の開発、数年にわたる運用、チーム間連携、曖昧な要件、壊滅的なリスクのいずれかに当てはまるなら、書く価値がある。判断に迷ったら「間違えたときの代償は何か」を自問しよう。ドキュメントに含めるべき項目とそうでない項目、レビューの進め方までを具体的に示す。
設計ドキュメントで考え得る限りの細部をすべて指定してしまったら、設計段階で実装を書き終えたのと同じだ。それでは設計ドキュメントの本来の目的が台無しになる。
HNでの議論
139- bob1029
ソフトウェア設計ドキュメントがプロセス全体を有意義に改善した状況に、私は一度も出くわしたことがない。せいぜい、納期がはるかに長くなるのを犠牲にして、ビジネス側との認識を揃えるのに役立つ程度だ。高レベルなソフトウェア納品契約でさえ、長く軌道に乗り続けることはまずないように思える。
とにかくその代物をさっさと作って、どこに着地するか見てみる方がたいてい速い。ソフトウェアは原子力発電所や沖合の石油プラットフォームとは違う。建設前に大量のことを事前に証明する必要なんてない。実際のところ、何をするにも誰かの許可が要るわけじゃない。縦に切り出したプロトタイプのリンクを、好きなタイミングでビジネス側にメールで送ればいい。それが「設計ドキュメント」で十分だ。
- mtlynch
著者です。この記事についてのフィードバックはいつでも歓迎します。
私はMicrosoftとGoogleで設計ドキュメントの書き方を学んだのですが、どちらの組織もドキュメント周りの文化が良く、それが他のエンジニアリングプラクティスほどには外に浸透していないと感じていました。設計ドキュメントの書き方について徹底的に解説したものを見たことがなかったので、これは私が学んだことを外に出そうとする試みです。
- wpollock
私の経験に基づく2つの提案です。
1)「起こりうる変更点」というセクションを追加しましょう。これは「不足している機能」よりも広い概念で、他にも例えば新しく利用可能になるかもしれないハードウェア、予想される顧客要件の変更、可能性のある新技術（例えば役立ちそうな新しいデータベースやクラウドサービス）、多言語対応なども含められます。こうした項目をいくつか列挙しておくと、レビュアーがさらに別の項目を思いつくきっかけになることがよくあります。
こうした変更を中心に設計をモジュール化しておけば、どれを実装するにしても、前提がコードベース全体にハードコードされている場合よりずっと簡単になります。
2) セキュリティとプライバシーは、より一般的な「コンプライアンス保証」というカテゴリの2つの側面です。この2つは独自のカテゴリにする価値がありますが、その他の法的・規制上・社内の要件を扱うセクションも設けるべきです。これらのコンプライアンスを監査する計画も記載しておきましょう。
もちろん、セキュリティとプライバシー以外に何もないこともよくあります。
- gwbas1c
参考までに、Lynch（著者）はHacker Newsのトップページに載せるための講座を販売しています：https://hitthefrontpage.com/
以前はLynchの記事を読む（あるいはざっと流し読みする）のが好きでしたが、彼がこうやってシステムを攻略して稼いでいるのを見て、私の中では評価が傷つきました。
- cowthulhu
私が仕様書を使うというアイデアに最初に目覚めたのはJoel Spolsky [https://www.joelonsoftware.com/2000/10/02/painless-functiona...] のおかげでした。
仕様書は価値があると思います。ソフトウェアの実際の機能（そしてその土台となる実装）についてじっくり考えさせてくれますし、あなたと［あなたが開発している相手］がおおよそ同じ認識を持つことを確実にしてくれます。さらに、仕様書を書いている間に見つけたエッジケースや設計上の問題は、その一つひとつが膨大な時間の節約になります。
とはいえ、仕様書の大きな弱点は、盲点が一切なく、実際に開発するときに遭遇するあらゆるエッジケースや問題を網羅した完璧な仕様書を書くなんてそもそも不可能だということだと思います。そのため、顧客に対して仕様書通りにやれと責任を問うのが難しくなります。なぜなら、あまりに文字通りで、実際には役に立たない製品を納品するのでもない限り、あなた（設計者と開発者）は仕様書に対して本当の意味で責任を負えないからです。
- randusername
私はDO-178C（航空宇宙）とIEC 62304（医療機器）のソフトウェア設計ドキュメントに携わったことがありますが、それらはスコープがずっと狭いです。
投稿者の設計ドキュメントは、規制対象のソフトウェア提出における完全なドキュメント一式の大部分をカバーできるほど包括的です。基本的に残っているのは、要件から設計、検証方法、検証結果へとトレースすることだけです。
- zumtrotz
揚げ足取りで申し訳ありません。
これはどちらかというとCONOPSかソフトウェアアーキテクチャドキュメントのように読めますが、高レベルな観点からすると十分に詳細ではなく、低レベルな観点からすると詳細すぎます（つまり、高レベルの設計ドキュメントには普通出てこないはずの実装の詳細が数か所あります）。
そういう観点で言うと、企業環境では誰が読者になるのかよくわかりません。アーキテクト向けなのか、他の開発者向けなのか、それとも自分自身向けなのか？
- Tsarp
この多くは時代遅れです。過去にはとても理にかなっていたもの、たとえばdiataxisやGoogleのガイドラインも含めて。
私はドキュメントをスキルの形で構造化し始めました。今日ではどのモデル／ハーネスもスキルをうまく扱えるように訓練されているからです。プロジェクトのドキュメント全体を、あるいはスキルとしてモデル化しています。
また、mdファイルには追加のフロントマターを付けています。具体的には2つのキーで、いつ読むべきか、いつこのドキュメントを読むべきでないか、です。これと、これを解析する簡単なCLIのおかげで、ドキュメント体験はずっと素早く快適になりました。
何かで本当に行き詰まったときには、その場でSVGやMermaidなどを生成することもできます。