アーキテクチャドキュメントに必要なこと [arch]

最近本腰を入れて大掛かりなアーキテクチャ設計をしようとしているが，ドキュメントを書く際にいつも帰ってくるのがこのエントリー．
Hitchhiker's Guide to Software Architecture and Everything Else - by Michael Stal: What should be in an Architecture Document?

とても素晴らしい内容なので，以下に意訳しておきます．ぜひ原文も合わせて読んでみて下さい．

- ドメインモデル (もしあれば)，使用されているパターン，ガイドラインなどに特化したドキュメントを合わせて紹介すること．アーキテクチャドキュメントは，それらのガイドラインと整合性を保つこと．

- 1つのドキュメントは50ページを超えないこと．肥大化したドキュメントは誰にも読まれない (少なくともその全ての内容は)．

- 当たり前のことだが念の為に言っておくと，標準的なドキュメントテンプレートを使うこと．

- 全てのドキュメントを，同じ書式で構成すること．さもないと (特に複数のドキュメントを読む) 読者は不快に思うだろう．

- ソフトウェアアーキテクチャはトップダウンで説明すること．抽象度の高い基本的なところから始め，少しずつその詳細や実装案件に踏み込んでいくこと．

こうすることで読者は自分が必要とする個所を抽出できる．例えば，マネージャーはアーキテクチャのざっくりした概要を捉えたいだけかもしれないし，エンジニアはハードウェアとの関係に興味があるかもしれない．

RUP の 4+1 (Four Plus One) view model を使うと良いだろう．まず最初に，動機やスコープなどを絡めつつ，アーキテクチャの「どの部分」を説明しようとしているかを明確にする．次にアーキテクチャ (とその方針決定) に影響を与えた全ての要件，及び設計の基となったユースケースを記述する．

コンテキストダイアグラムは，アーキテクチャの境界，及びシステムのその他の部分にどう統合されるかを説明するのに使えるだろう．CRC (Class-Responsibility-Collaborator) カード，クラス図，シーケンス図などを用いて，(4+1の) 論理ビューを記述すること．

技術に特化した案件を早期に提示するべきではない．例えば，プロジェクトで .NET Remoting や C#，SQL サーバなどを使っていたとしても，アーキテクチャ基盤は (少なくともその論理構造は) それらの技術に依存するべきではないからだ．

Deployment View (配置図) に辿りつくまで，少しずつ精度を上げつつドキュメントを書き上げること．

- UML，ER (Entity Relation)，DSL (Domain Specific Languages) などにおいて，対称性を保つ為に同じ目的には同じダイアグラムを使うこと．さらにこれらのダイアグラムが，同じメタモデルを使うこと．例えば，プロジェクト・ドメインに特化して定型化された概念は，(最初の項目でも触れたように) 別シートを参照すること．

- 専門用語や略語などを説明する用語集を提供すること．全てのドキュメントは，同じ意味なら同じ用語を使うこと．

- 読者がドキュメントを理解する為に必要と思われる，他の参考文献を明示すること．

- 自明ではない設計方針は説明すること．根拠が示されていないアーキテクチャドキュメントをこれまで幾多と見てきたが，他のアーキテクトがドキュメントを読んだ時，設計根拠は必ず理解されなければならない (つまり what だけではなく why も)．根拠を理解するということは，アーキテクチャを理解することと同じである．

- 前項と同じ理由で，アーキテクチャがいかに要求を満たすかを記述すること．こうすることで要求追跡が可能となる．

- パターンを使うこと，そしてそのパターンを説明すること．その時に，パターンの完全解説を行う必要はなく，現存の書籍やパターン解説ドキュメントを参照する形が望ましい．

- ツリーのように階層構造を持たせてドキュメントを構成すること．ルートでは，システムの全体戦略を記述し，適切なサブシステムや，セキュリティ・スケーラビリティといった横断的な案件を説明する．

- ルート直下のノードには，サブシステムやその他重要な横断的案件をを示す．もしサブシステムがその中に大きな構成要素を含んでいるなら，それを説明するリーフを足していくと良いだろう．

- テスト容易性について言及しておくこと．これによりアーキテクチャの仕様が定義されるだけでなく，その実装がどのようにテストされるかが明確になる．

- ドキュメントは構成管理ツールを使って管理すること．ドキュメントはバージョン管理すること．

- ドキュメントの表紙に主な著者，もしくは全ての著者，及び日付けとバージョンを記述すること．

- ドキュメント (と設計) は他者にレビューしてもらうこと．読みやすさと技術専門性についてフィードバックを受けること．同じチームに属する同僚だけではなく，マネージャー・アーキテクト・テスターなどの人からもレビューを受けること．

- もう少しプロセス寄りの話として，アーキテクチャドキュメントは現状の実装を反映すること (もしそれが既にあれば)．さもなければ，そのドキュメントを読むという行為はまったく時間の無駄であり，他のチームに間違った判断を促すことにすらなる．

- 設計はダイアグラムや図を用いて説明すること．特に複雑なアーキテクチャ案件についてはそうすること．まったく図がない，文字で埋めつくされたドキュメントを理解をすることはできない．図を書くことは面倒でもあるが，その時間を費やすだけの価値はある．

こちらも合わせてご参考．
Peace Pipe: ソフトウェアアーキテクチャ その11 - 健全なドキュメントを書く7つのルール [arch]
Peace Pipe: ソフトウェアアーキテクチャ その12 - ドキュメントを書く上での6つのテクニック [arch]