大規模なチーム開発をする場合、
- 要求定義書
- 要件定義書
- ER図
- テーブル定義書
- 基本設計書
- 詳細設計書（シーケンス図）
- ログ設計書
- テスト仕様書
など、多くのドキュメントを用意すると思います。
しかし、これが5〜3人未満のチームの場合ここまでの数のドキュメントを揃えると開発スピードとの天秤にかけるとデメリットの方が大きいです。
ドキュメントを整える意味は「情報伝達」です。
人数が多いほどコミュニケーションコストが増すため、ドキュメントはそのコミュニケーションコストを下げる助けとなるものとして記載されるべきだと思います。
とはいえ、個人で開発から運用まで行う場合以外はビジネスサイドとの意思疎通のためにもドキュメントは必須だと思います。
そこで、小さいチームの中でドキュメントを作っていく中でDesign Docの活用をひとつのアイディアとして紹介します。
今回、2種類のテンプレートを用意しました。
ひとつは、メルカリの技術ブログの中で紹介されてる以下の記事を日本語訳にしたものです。
正確ではないのですが大枠は揃えています。
テンプレート
機能概要
全てのエンジニアが理解し、このドキュメントを読むべきかどうかを判断するための高レベルな要約です。3段落以内で簡潔にプロジェクトの内容を説明します。
実装背景
このプロジェクトが必要とされる理由や問題点について記載します。また、このプロジェクトがどのように技術的戦略や製品戦略、チームの四半期目標に関連しているか、またはプロジェクトを評価する際に知っておくべきことを説明します。
影響・対象範囲
このドキュメントがカバーする範囲について記載します。
ゴール
目標セクションでは、以下の内容を含めます：
– このプロジェクトがユーザーにどのような影響を与えるのかを説明します。ユーザーは他のエンジニアリングチームや技術システムそのものの場合もあります。
– 成功を測定するための指標を明確にし、その指標をトラッキングするダッシュボードへのリンクがあると尚良いです。
対象外項目
非目標は、解決しない問題について明確に記述します。これにより、関係者全員が同じ認識を持つことができます。
解決策 / 技術アーキテクチャ
ユーザーストーリーを基に具体化しながら、解決策を説明します。複数のサブセクションや図表を含めて構いません。最初に全体像を説明し、その後で詳細に入ります。理想は、このドキュメントを読んだ別のエンジニアが、著者不在でも解決策を実装できることです。
システムコンテキスト図
システムが技術的な全体像の中でどのような位置にあるかを示す「システムコンテキスト図」を用意すると、読者が新しい設計を理解しやすくなります。
API
データを保存するシステムについては、その保存方法や大まかな形式について説明します。APIに関しても、設計に関係する重要な部分に焦点を当て、完全なスキーマ定義のコピーを避けます。
データストレージ
データ保存に関する詳細も含めます。API同様、設計上のトレードオフに関連する部分だけに焦点を当てます。
代替案
上記の解決策以外にどのような選択肢を検討したかを説明します。また、その代替案のメリット・デメリットを比較します。問題を自社開発するのではなく、サードパーティのソリューションやオープンソースを使用する選択肢も考慮したかどうかも記載します。
マイルストーン
設計・要件整理
実装
内部レビュー・テスト
UAT
リリース
実装の懸念点
ログ・GA設計
セキュリティの考慮
可観測性
参考資料
次に、上記をプロンプトとしてChatGPTに作成してもらったものを記載します。
タイトル（Title）
プロジェクトやシステムの名前や、設計の対象となる機能やサービスの概要。
概要（Overview / Executive Summary）
設計に関する簡潔な概要を記載します。目的、背景、問題の要約、設計の意図や目標を短く説明します。
このセクションは、ドキュメント全体を素早く理解するための要約として使われます。
背景と動機（Background and Motivation）
プロジェクトや機能を開発する理由や背景を記述します。何が問題となっているのか、なぜこの設計が必要かを明確にします。
既存のシステムや機能に対する問題点や制約、改善点についても触れることが多いです。
目標と非目標（Goals and Non-goals）
設計によって達成したい具体的な目標をリスト化します（スコープの定義）。
あわせて、この設計で扱わない内容（非目標）を明示し、期待を明確にしておきます。
要件（Requirements）
システムや機能に必要な要件（機能的要件や非機能的要件）を明確にします。例えば、パフォーマンス要件、セキュリティ要件、スケーラビリティ、可用性など。
アーキテクチャ（Architecture / High-Level Design）
システムの全体像や高レベルの設計を説明します。システム全体の構造や、主要なコンポーネントの関係を図示することが一般的です。
サービスやモジュール間のインタラクション、データフロー、依存関係などを示すことが多いです。
詳細設計（Detailed Design）
アーキテクチャセクションで示した高レベルの設計を詳細化します。具体的なモジュールやコンポーネントの動作、アルゴリズム、インターフェースの設計について詳述します。
ここでは、重要なデータ構造、クラス設計、API、フローなども含まれます。
技術的選択肢とトレードオフ（Technical Choices and Trade-offs）
設計を進めるにあたって考慮した技術的な選択肢や、それらの選択肢間のトレードオフを記載します。
代替案やそれぞれのメリット・デメリット、選択した理由も明記します。これにより、将来的に設計の妥当性を確認しやすくなります。
データフロー（Data Flow / Sequence Diagrams）
ユーザーや他のシステムとのインタラクションや、データの流れを説明します。シーケンス図やデータフローダイアグラム（DFD）を使用して視覚的に示すことが一般的です。
10. エラー処理とリカバリ（Error Handling and Recovery）
エラーハンドリングや、システムがどのようにエラーを管理し、リカバリするのかについて説明します。
11. パフォーマンス（Performance Considerations）
システムの性能に関する要件や期待値、パフォーマンスの測定・最適化方法について記載します。
12. セキュリティとプライバシー（Security and Privacy Considerations）
システムにおけるセキュリティの考慮点や、プライバシーの保護について記述します。どのような攻撃に対して保護されるか、データの機密性や整合性がどのように確保されるかを説明します。
13. テスト計画（Testing Plan）
システムや機能がどのようにテストされるか、テストの戦略や自動化のアプローチを記載します。ユニットテスト、統合テスト、負荷テストなどの種類も含めます。
14. デプロイメント戦略（Deployment Strategy）
設計したシステムや機能がどのように展開されるか、リリースプランや、バージョン管理、ローリングアップデートなどの手法を記載します。
15. 監視と可観測性（Monitoring and Observability）
システムが稼働中にどのようにモニタリングされ、可観測性が確保されるかを説明します。ログ、メトリクス、トレースの方法なども含めます。
16. リスクと緩和策（Risks and Mitigations）
設計や実装に関連するリスクを洗い出し、それに対する緩和策（mitigation）を示します。たとえば、技術的な不確実性やリリースの失敗などを考慮します。
17. タイムライン（Timeline）
プロジェクトの実装、テスト、デプロイに関するスケジュールやマイルストーンを記載します。
18. 結論（Conclusion）
設計の総括や、次のステップについて簡潔にまとめます。
使用するツールについて
ドキュメントで使用するツールについては、自由に選びにくいケースもあるかもしれませんが
Google系のものでドキュメントを統一することで別ドキュメントのリンクを貼った時にとてもみやすくなるため推奨します。
他にも別ドキュメントのリンクが見やすいツールであれば積極的に採用した方が見やすさ・検索しやすさに繋がるためツール検討の1項目として取り入れていただければと思います。