ソフトウェアアーキテクチャの文書化
アーキテクチャ文書は、利害関係者がシステムの存続期間中に会議で尋ねてくるであろう質問に答えるために存在します。これはどのように構成されているのか？なぜこのようになっているのか？Xを変更するにはどこを変更すればよいか？Yの条件下でこれは持続するか？ 優れた文書は、これらの質問に一度だけ、書面で、各読者が実際に使える形で答えます。
このスキルは、そのような文書を作成するための方法、および他の誰かが書いた文書をレビューするための方法です。このスキルは、特定の著作権のあるテキストではなく、オープンで自由に利用できる標準とモデルに基づいています。
- ISO/IEC/IEEE 42010 — アーキテクチャ記述の国際標準です。ここで使用される語彙（利害関係者、懸念事項、ビューポイント、ビュー、モデル、アーキテクチャ決定、根拠）を提供します。
- C4モデル (Simon Brown) — コンテキスト、コンテナ、コンポーネント、コードの4つのズームレベルによる軽量な構造図のセットです。
- 4+1ビューモデル (Philippe Kruchten) — 論理、プロセス、開発、物理の4つのビューと、それらを結びつけるシナリオ（+1）という5つの並行する視点です。
- arc42 — クリエイティブ・コモンズの文書化テンプレートであり、そのセクション構造は完全なアーキテクチャ記述の実用的な骨格となります。
- アーキテクチャ決定記録 (Michael Nygard によって普及した ADR 形式) — 重要な決定ごとに1つの短いファイルです。
方法
文書化は、誰が読むか、そして彼らが何を決定または実行する必要があるかによって推進されます。以下の順序で作業を進めてください。
-
利害関係者とその懸念事項を特定する。 アーキテクチャに依存する人々（開発者、運用担当者、セキュリティレビュー担当者、プロダクトオーナー、統合担当者、監査担当者）をリストアップし、それぞれが文書に何を期待しているかを把握します。懸念事項とは、誰かにとって重要な質問や品質のことです：「ダウンタイムなしでこれをデプロイできるか？」「顧客データはどこにあるのか？」「新しい決済プロバイダを追加するにはどうすればよいか？」。懸念事項が後続のすべてを決定します。
references/viewpoints-and-views.mdを参照してください。 -
懸念事項をカバーするビューポイントを選択する。 ビューポイントとは、再利用可能な種類のビュー、すなわち、あるタイプの表現（どの要素を示すか、どのような関係を示すか、どのような表記法を使うか）を構築するための規約です。すべての重要な懸念事項に対処する、最小限のビューポイントセットを選択してください。誰も必要としないビューを書いてはいけません。
references/view-catalog.mdを参照してください。 -
ビューを構築する。 各ビューは、あるビューポイントからのシステムの1つの表現です：図とそれを説明する散文です。ほとんどのシステムでは、構造ビュー（構成要素とそれらの依存関係）、実行時ビュー（実行時に何が起こるか：プロセス、フロー、相互作用）、およびデプロイメントビュー（ソフトウェアがインフラストラクチャにどのようにマッピングされるか）が必要です。タイミングや順序が重要となる部分については、振る舞いビューを追加します。C4レベルと4+1の視点は、これらを具体化するための具体的で実績のある方法です。
references/view-catalog.mdを参照してください。 -
決定とその根拠を記録する。 アーキテクチャ文書の中で最も価値が高く、最も頻繁に欠落している部分はなぜです。重要な決定（コンテキスト、検討した選択肢、選択、および結果）をそれぞれアーキテクチャ決定記録として記録します。根拠は、次の担当者が推測する代わりに安全にシステムを変更することを可能にします。
references/decisions-and-rationale.mdを参照してください。 -
記述をまとめ、方向性を追加する。 ビューの集まりは文書ではありません。接続組織を追加します：1ページのシステム概要、スコープとコンテキストの記述、用語集、およびビュー同士の関係に関する明示的な注記（同じ要素が2つのビューに現れることは読者の主な混乱の原因であるため、それを解決します）。完全なセクション骨格については
references/documentation-template.mdを使用してください。 -
公開前にレビューする。
references/review-checklist.mdに対して文書をチェックします。2つの失敗モードは、不完全性（どのビューも対処していない懸念事項がある）と読みにくさ（凡例のない図、未定義の用語、読者が何を見ているのかの説明がない）です。
このスキルの使い方
- ゼロから始める場合 → 上記の6つのステップに従い、
references/documentation-template.mdを目標構造として使用します。 - 何を書くか決める場合 →
references/viewpoints-and-views.md（懸念事項→ビューポイント）とreferences/view-catalog.md（ビュータイプのカタログ）を参照します。 - 決定を記録する場合 →
references/decisions-and-rationale.md（ADR 形式と例）を参照します。 - 既存の文書をレビューする場合 →
references/review-checklist.mdを参照します。 - フレームワーク間の選択やマッピングを行う場合 →
references/frameworks-map.mdを参照します。
原則
- 完全性ではなく読者のために書く。 すべてのビュー、図、段落は、利害関係者の懸念事項にたどり着く必要があります。誰が必要としているのか名前を挙げられないなら、削除してください。
- すべての図には凡例が必要。 「明らかに見える」表記法はそうではありません。ボックスと線が何を意味するかを明記してください。説明のない図は、間違っていることが待っている推測です。
- 決定の根拠はその都度記録する。 決定は、行った瞬間に記録するのは簡単ですが、後で再構築するのは高くつきます。
- コードの近くに保ち、最新に保つ。 現実から乖離した文書は、人々がそれを信頼するため、まったくないより悪いです。維持管理しない大きな文書よりも、維持管理する小さな文書を選んでください。
- システムのリスクに応じて深さを設定する。 間違えるとコストが高い部分は詳細に文書化し、その他はスケッチ程度に留めてください。