write-design-docs

設計ドキュメントを書く

基本的なワークフロー

設計ドキュメントは、実装マニュアルではなく、問題解決と合意形成のためのツールとして使用します。

1. 設計ドキュメントが必要かどうかを判断します。

   • ソフトウェアの設計が曖昧、複雑、意見が分かれている、複数の機能領域にまたがる場合、シニアメンバーのレビューが有益と見込まれる場合、または組織の記録として価値がある場合は、作成します。
   • 解決策が明白で、意味のあるトレードオフがない場合は、短いメモ、課題、または直接の実装を優先します。
   • 小規模でも自明ではない変更には、簡易設計ドキュメントを優先します。

2. 設計を具体化するために必要な最小限の情報を集めます。

   • 問題、既存の状況、制約、関係者、意思決定の期限を特定します。
   • 不足している情報によって目標、対象外事項、またはトレードオフが大きく変わる場合に限り、焦点を絞った質問をします。
   • 不完全な情報のまま進める場合は、前提を明示します。

3. 意思決定とトレードオフを中心に草案を作成します。

   • 客観的な背景とスコープから始めます。
   • 目標と対象外事項を明確な境界として定義します。
   • 選択した設計を、概要から詳細へと説明します。
   • 既知の制約のもとで、選択した設計が目標を最もよく満たす理由を説明します。
   • 現実的な代替案を比較し、選択しなかった理由も含めます。
   • 該当する場合は、セキュリティ、プライバシー、信頼性、可観測性、移行、運用など、横断的な懸念事項を扱います。

4. ドキュメントを読みやすく保ちます。

   • すべての実装詳細ではなく、意思決定を把握する必要がある多忙なレビュアー向けに最適化します。
   • 詳細な要件、プロトタイプ、スキーマ、コード、過去のドキュメントは、そっくりそのままコピーするのではなくリンクします。
   • 設計上のトレードオフを明確にする場合に限り、図や簡潔な API／データの例を含めます。
   • 新しいアルゴリズムの説明以外では、大きなコードブロックを避けます。

5. ドキュメントのライフサイクルを整えます。

   • ドキュメントのステータスを明記します。draft、in review、accepted、implementing、superseded、または archived とします。
   • まず必要最小限のレビューチームを提案し、設計が固まってからレビュー範囲を広げます。
   • システムのリリース前に、実装によって前提の誤りや要件の変更が判明した場合は、ドキュメントを更新します。
   • 元のドキュメントと実際の状況に乖離が生じた場合は、修正や後続ドキュメントへのリンクを追加します。

参考資料

本格的な設計ドキュメントを作成またはレビューする前に、references/design-doc-guidance.md を読んでください。記事に基づくテンプレート、意思決定チェックリスト、各セクションのガイダンス、レビュー基準として活用してください。