- Design docsはGoogleのソフトウェアエンジニアリング文化の中核要素の1つであり、ソフトウェアシステムやアプリケーションの主要な作成者がコーディングプロジェクトを始める前に作成する、比較的インフォーマルな文書
- 高水準の実装戦略と主要な設計判断を文書化し、特にそれらの判断時に検討されたトレードオフに重点を置く
- ソフトウェアエンジニアの仕事はコードを書くことではなく問題を解決することであり、Design docのような非構造化テキストは、プロジェクト初期段階ではコードよりも簡潔で理解しやすい問題解決ツールになり得る
Design docsのソフトウェア開発ライフサイクルにおける役割
- 本来のソフトウェア設計の文書化に加えて、次のような機能を果たす:
- 変更コストがまだ低い段階で設計上の問題を早期に特定
- 組織内で設計に関する合意を形成
- 横断的関心事（cross-cutting concern）への配慮を保証
- シニアエンジニアの知識を組織へ広める
- 設計判断に関する組織的記憶の土台を作る
- ソフトウェア設計者の技術ポートフォリオにおける要約アーティファクトの役割
Design docの構造
- Design docには厳格なコンテンツガイドラインがないインフォーマルな文書であるため、特定のプロジェクトに最も適した形式で作成するのが原則
- Context and scope: 新しいシステムが構築される背景と、実際に何を構築するのかの概要を提供
- Goals and non-goals: システムの目標と、目標ではないものを列挙
- The actual design
- System-context-diagram: システムをより大きな技術環境の一部として示す図
- APIs: システムが公開するAPIのスケッチ
- Data storage: データを保存・管理する方法を議論
- Code and pseudo-code: 新しいアルゴリズムを説明するときにのみ含める
- Degree of constraint: 解空間の制約の度合いは、設計文書の形に影響を与える主要因の1つ
- Alternatives considered: 類似した結果を合理的に達成できる代替設計を列挙し、各設計のトレードオフと主要設計を選んだ理由を説明
- Cross-cutting concerns: セキュリティ、プライバシー、可観測性など、組織の共通関心事が設計にどのような影響を与えるかを説明
Design docを書くタイミング
- Design docを作成するかどうかは、設計に関する組織的合意、文書化、シニアレビューなどの利点が、文書作成に伴う追加作業を上回るかにかかっている
- 問題の複雑さやソリューションの複雑さによって設計課題への解決策が曖昧である場合でなければ、文書作成の価値は低い
- 実装マニュアルに近いDesign docは不要なことがある
- プロトタイピングや迅速な反復には、Design doc作成のオーバーヘッドが適さないことがある
Design docのライフサイクル
- Creation and rapid iteration: 文書を作成し、同僚との迅速な反復を通じて安定版を導く
- Review: より広い読者と共有され、レビューされる
- Implementation and iteration: 実装中に設計変更が発生した場合は文書を更新
- Maintenance and learning: システムを理解するための最もアクセスしやすい入り口として機能
GN⁺の意見
- Design docは、複雑なソフトウェアプロジェクトの最も難しい問題を解くうえで明確さを得て合意を形成するための良い方法。事前調査によって不要なコーディングを避けられるためコスト削減につながる一方、作成とレビューには時間がかかるためコストも発生する
- したがって、プロジェクトに合わせてDesign doc作成の可否を賢く選ぶ必要がある。ソフトウェア設計に不確実性があり、シニアエンジニアの早期関与が有用で、設計に関する組織的合意が必要であり、チームがセキュリティなどの共通関心事をしばしば見落とし、レガシーシステム設計に関する高水準の文書が必要な場合は、Design doc作成を検討する価値がある
- ソフトウェア設計プロセスにおける文書化の重要性をよく示す事例であり、特に大規模チームで一貫した設計文化を確立するのに役立ちそう。ただし、文書化の負担からエンジニアが敬遠する可能性もあるため、状況に応じた適切なレベルと範囲でガイドラインを整備することが重要に見える
- 個人的には、1) 設計の複雑さに応じたトレードオフの検討、2) 実装前の設計課題の早期発見、3) 新規メンバーの迅速な学習のためのシステム概要の提供という点で、Design docの有用性は大きいと考える。ただし、過度に形式的だったり、実際の実装と乖離した文書にならないよう注意が必要
- プロジェクト初期、あるいは複雑性の高い設計段階に限ってDesign docを義務化しつつ、エンジニアが自発的に作成できるようインセンティブを提供するのも1つの方法。文書作成が個々のエンジニアの技術ポートフォリオ強化にも役立つ点を強調するとよい
1件のコメント
Hacker Newsの意見
Googleのデザインドキュメント文化に関するさまざまな意見: