概要
システム設計においてアーキテクチャドキュメントは重要な役割を果たす。特に設計段階においては、関係者に対して設計の妥当性を説明し、合意を形成するための資料として機能する。このドキュメントは、単なる設計情報の羅列ではなく、読者の理解と納得を導くための戦略的な文書であるべきである。
目的を明確にする
ドキュメントを作成するにあたって最初に意識すべきは、その目的である。この文書が誰に向けたものであり、何を伝えることを目的としているのかをはっきりさせなければならない。主な対象はプロジェクトのステークホルダーである。彼らが抱える関心事に応え、理解できる内容であることが求められる。
ドキュメントが備えるべき特性
正確性
記述内容は、対象となるアーキテクチャやステークホルダーの関心事に対して正確でなければならない。また、提案されたアーキテクチャがステークホルダーのニーズに合致していることも明確にすべきである。
十分性
単に構成要素を並べるのではなく、なぜそのような構成を採用したのかという判断理由を示す必要がある。代替案があった場合はその比較や却下理由も論理的に説明することで、設計の説得力が増す。
簡潔性
すべてを詳細に書くのではなく、重要な設計判断に焦点を絞ることが大切である。詳細の程度は以下の観点で調整すべきである：
- ステークホルダーの技術的能力と経験
- 内容の先進性
- 解決しようとする問題の複雑さ
- 利用可能なコミュニケーションの時間とリソース
明瞭性
読み手の知識や理解の程度に合わせ、専門用語の使い方や表現を調整することが重要である。図や表を使って視覚的に伝える工夫も効果的である。
通用性
ドキュメントは最新の設計状況を反映している必要がある。設計が進化していく中で、ドキュメントも定期的に更新されなければ意味をなさない。
精密性
実装に着手できる程度にまで、必要な詳細は記述しておくべきである。ただし、詳細に書きすぎると可読性が損なわれるため、図や別文書の併用、具体と抽象の使い分けによってバランスを取ることが求められる。
構成の例
以下にアーキテクチャドキュメントの構成例を示す。筆者がドキュメント書く際に意識しているポイントを含めている。
概論
- ドキュメントの目的
- 想定読者
- システムの目標の要約
- スコープの要約
- 解決策の要約
要件定義
- 機能要件
- 非機能要件
- 特記事項（規制、前提条件、制約など）
アーキテクチャ図
- システムの構成要素とその関係、外部システムとの関係を示す図（C4モデルが有効）
- 特記事項（信頼境界、可用性の観点、など）
データモデル
- 扱う主要なデータ構造の図（ER図やスキーマ図など）
- 特記事項（個人情報の取り扱い、法的制約など）
ユースケース
- 主要な利用シナリオを記述し、設計判断の背景となる業務文脈を示す
技術詳細
- 使用技術スタック、フレームワーク、ライブラリなど
- 技術選定理由や設計上の工夫についての解説
リスクと課題
- 現時点で想定されるリスク
- 技術的、業務的な課題とその対応方針
展望
- システムの将来的な拡張や改善の方向性
- 可用性、スケーラビリティ、保守性の展望
未解決事項
- 今後の検討が必要なポイントや保留中の課題
関連ドキュメント
- 詳細仕様書、業務フロー図、プロジェクト計画書などへのリンク
まとめ
ステークホルダーが誰か？ということがドキュメントの内容を左右する変数になっている。
開発者だけを対象としたドキュメントであれば、開発者が執筆する上では比較的容易であるが、プロジェクトマネージャーやセールスなど、技術的な背景を持たないステークホルダーを対象とする場合は、より注意深い配慮が必要になる。
ついつい複数のことを一度に説明しようとするような文書や図を作成してしまいがちであるが、読者の理解を助けるためには、情報を整理し、焦点を絞った内容にすることが重要になる。
私自身は、簡潔性を一番最初に意識して、その後にそれ以外の観点を捉えていけるように調整するというプロセスを取ることが多い。最初から詳細を含めすぎると自分自身にとっても認知負荷が高くなってしまうため、まずは全体像を把握し、そこから必要な情報を追加していく形でドキュメントを構築することが多い。