私たちはアプリケーションの内部状態を反映することを目的に、（技術ドキュメントの一部として）アーキテクチャ図を作ろうとするが、ほとんどの場合、うまく作れていない。こうして作られた図は、非常に包括的なものから極めて曖昧なものまで、多種多様だ。そもそも図が適切でない場合もある。私は以前、役に立つアーキテクチャ図の作り方について、いくつかヒントを書いた。
たとえ適切な図が作られたとしても、統合された継続的開発プロセスの中で機能が開発されるのに合わせて、これらドキュメントが継続的に更新されることはめったにない。現実には、ドキュメントは時々しか更新されない。おそらく（そうしたアクティビティの時間がある）一部のスプリントや、特定のリリースでしか更新されないだろう。私が話をした開発者（同僚や私のSoftware Architectureコースに参加している学生）のほとんどは、技術ドキュメントを作成して保守するのを嫌がっている。単調で、時間がかかり、他の作業よりも価値が低いと思っているのだ。ソースコードがうまく書けていれば、ドキュメントは不要だと考える人すらいる。例外は常にあるが、ことアーキテクチャ図に関して言えば、ほとんどのプロジェクトで同じような状況だろう。
どこが悪いのか、どうすれば改善できるか
まず第一に、アーキテクチャ図と技術ドキュメントの真の受益者が誰なのか、理解することが重要だ。ドキュメントの量と質は、ステークホルダーのニーズを反映しなくてはならない。そうしてはじめて、正確かつ十分なだけのドキュメントを作成できるためだ。
主な受益者は、プロジェクトに直接関与するチーム（開発者、テストエンジニア、ビジネスアナリスト、DevOpsなど）になるはずだ。私の経験上、チーム外にいるステークホルダーのほとんどは、ドキュメントを本当には気にしていない。彼らはせいぜい、システム構造の概略を説明し、ハイレベルな理解を与えてくれる1つ2つのハイレベルな図（コンテキスト図、アプリケーションおよびソフトウェアコンポーネント図）に関心があるぐらいだろう。
しかし、たいていの場合、私たちは真の受益者と彼らの真のニーズをうまく特定できずに、ドキュメントを過大に作ろうとしてしまう。そしてドキュメントの保守はすぐに負担となり、早々に時代遅れなものになってしまう。さもなくば、時間がない、特別な関心がない、誰も責任を持ちたくない、といった理由で、さまざまな図の作成を省略してしまう。加えて、アジャイルマニフェストは、チームは包括的なドキュメントよりも動くソフトウェアに価値を置くべきだ、と定めており、面倒なドキュメンテーションプロセスを思いとどまらせている。
正しいドキュメントの適切なバランスを見つけるために、次のエクササイズをチームで試してみよう。まず各同僚に、技術ドキュメントに本当に必要なもの、そこに含めるべき図の種類について質問する。彼らの意見を集約して、ブレインストーミングを実施し、チームにとって本当に必要なものについて合意をとる。チームの外部に、追加の要求を持つ影響力のあるステークホルダーが1、2名いるかもしれない。彼らのニーズを考慮することもまた、アーキテクトの責務だ。以上に基づいて、ステークホルダーのニーズを満たす適切な量とレベルの技術ドキュメントを作成する。もし開発者がドキュメントの真の価値を理解し、その価値を保つことに関心を持てるなら、進んでドキュメントに貢献し、適切に保守してくれるだろう。最終的に、全員がハッピーになる。しかし、もしその必要性を理解しなかったり、気にしないのなら、それについてはほとんど忘れてしまって構わない。チームメンバーで分担する必要があるのに、（アーキテクト）一人だけでドキュメントを保守するのは、非常に難しくなるためだ。
これまでウォーターフォールプロジェクトでは、包括的なエンタープライズアーキテクチャ方法論（名指しするのは意図的に控えた）に由来するドキュメント、もしくは象牙の塔にいるアーキテクトに要求されたドキュメントを作りすぎていた。アジャイル手法がソフトウェアプロジェクトで大規模に採用されたとき、よくある大きな誤解は、どんなドキュメントも不要だと考えてしまうことだった。動くソフトウェアを作ることは包括的なドキュメントを作ることよりも重要だからだ。もちろん、これら2つは極端なケースだ。「プロジェクトにとって適切なドキュメントの量」という課題にはっきり取り組んだ、精度の高い方法論や科学的プロセスは存在しない。現在のソフトウェアアーキテクチャ手法はすべて、純然たる推奨あるいはガイドラインだ。これまで従っていた包括的なアーキテクチャプロセスは、今やプロジェクトに存在しないくらい大幅に簡単化されている。このことは、ドキュメントをもっと減らす、あるいは全く作るべきではないことを意味している訳ではない。むしろ、真の価値を提供するドキュメントの作成に注力するのと同時に、チームの前進を妨げないことを意味している。何より、すべてのドキュメントが価値を提供しているわけではない。しかし「すべてのドキュメントが価値を提供していない」と同じではないのだ。それに加えて、あるプロジェクトに意味があるドキュメントも、コンテキスト（例えば、経済的あるいは政治的など）、ビジネス目標、ステークホルダーなどの違いにより、別のプロジェクトにはあまり関係ないかもしれない。
このような状況下において、適切な技術ドキュメント（すなわち、アーキテクチャ図）の量は？、という質問にはっきり答えるのは非常に難しいことだ。結局のところ、それは各 プロジェクト、そしてアーキテクトの経験に関連しており、簡単に言えば「場合による」になるだろう。価値を提供する適切なドキュメントの量は、チームが必要だと判断したものによる。私からのアドバイスは、チームと一緒に判断し、それがチームにとってどんな意味を持つものであれ、十分なだけの技術ドキュメントを作ることだ。あなたのプロジェクトにとってドキュメントに意味がないなら（どうして？）、それでも構わないだろう。そのチーム合意の背景にある理論的根拠をドキュメント化して、すべてのステークホルダーに見えるようにしよう。本当に関心のある図が2、3あるなら、それらを更新し、一貫性を持たせ、システムの状態を常に反映させるようにしよう。価値をもたらさないものに注力してはいけない。
でも、なぜアーキテクチャ図を必要とするのか？
特にアーキテクチャ図とそのドキュメントは、主にチーム内外とのコラボレーション、コミュニケーション、ビジョン、ガイダンスのために使う必要がある。また、（ある時点に下された）プロジェクトの重要な設計判断を含んでいる必要があるが、それ以上のものは不要だ。
アーキテクチャ図は、全員が全体像を見て、周りを理解するのを助けるものでなくてはならない。私の意見では、これはアーキテクチャ図を作成して保守する根本的な理由になるはずだ。
例えば、コンテキスト図はそうしたニーズを完全に満たしていて、全体像を見せながら、システム境界の詳細レベルを提供する。これはチームに共通理解を持たせて、様々なステークホルダーとのコミュニケーションを容易にするのに役に立つ。こうしたコンテキスト図を巨大なスクリーンに表示して、多くの質問を省き、ハイレベルなシステムアーキテクチャに関する不確実さを取り除く、そういうミーティングに私は数多く出席した。
しかし、システムの内部状態を反映するように、包括的なドキュメントを作ろうとすることがよくある。これはステート図、アクティビティ図、クラス図、エンティティ図、コンカレンシー図といった形式になるかもしれない。だが「魔法のような」ツールを使ってソースコードから自動生成しない限り、こうしたものはすぐに時代遅れになる。
必要とされていない、読まれていない、理解されていないのなら、そうした詳細な図を作成する目的はどこにあるのだろうか？ ビジネスステークホルダーにとって、抽象的な図があれば十分すぎるほどだ。開発者にとって、アプリケーションを理解するために本当に必要なものは、ほとんどの場合、ソースコード（すなわち、信頼できる唯一の情報源）だ。したがって、コードで一目瞭然なもの、詳細すぎるもの、実際に読む人がいない時は、図を作るのをやめよう。
意味がある最小限のアーキテクチャ図を作って、それを技術ドキュメントに組み入れよう。ほとんどのアプリケーションの場合、必要とされる重要な図は2、3種類になるだろう。もっとも一般的なのは、コンテキスト図、アプリケーション/ソフトウェアコンポーネント図、システム図、デプロイメント図といったものだ。
実例
私のプロジェクトでは、主に2種類の図を使っている。
- コンテキスト図
- アプリケーションまたはソフトウェアコンポーネント図
これらの図は、提供すべき妥当な情報に関するガイダンスを示す単純な例として扱ってほしい。図にある情報は、対応する抽象化レベルに関連しているが、ステークホルダーのニーズを満たしている必要がある。実際には、図にどんどん詳細を追加したくなるだろう。しかし、受益者にとって本当に有用なものでない限り、それらは余計なノイズ、保守の増加、期限切れのリスクにつながる。こうした図に特有な、プロトコルやデータ形式といった詳細な情報は、実装に必要になる情報であるため、技術ステークホルダーにとって非常に便利かもしれない。しかし、記事でも述べたように、図が含むべき詳細情報の適切な量をはっきりと説明した精度の高い方法論は存在しない。実際には、プロジェクトごとに違うものだ。とはいえアーキテクトは、ステークホルダーにとって本当に有用なものを特定し、それをうまく反映するように図を作成し、保守しなくてはならない。
これら図以外の詳細については、ソースコードで見つけたり、ツールで自動生成してもよいだろう（例えば、ランタイムビュー図、デプロイメントビュー図、システムまたはインフラストラクチャビュー図など）。
私はミーティングルームで、ソフトウェアアーキテクチャ図（すべてのアプリケーションコンポーネントを含む）を描いていた。スタンドアップなどのミーティング中、壁にある図を指差しながら、タスク、ステータス、障害について話し合うのだ。こうして、プロダクトオーナーから開発者まで、チームメンバー全員が全体像を理解し、全体的な障害やインテグレーション問題を予測する。加えて、特にアーキテクチャが分散されていて人々の間に依存関係がある場合には、チーム全体のスプリントでより正確な進捗状況を提供する。
あなたのチームも同じようにすることをアドバイスしたい。十分なだけのアーキテクチャ図を使うことで、コラボレーション、コミュニケーション、ビジョン、ガイダンスを高め続けよう。そして、他の理由、特にチームがそれを使わないなら、作るのをやめてしまおう。コードの振る舞いを反映するように、手作業で図を作成して保守するのは、ほとんどの場合、時間の無駄だ。そうしていると、ソースコードの進化に合わせて図をどんどん追加したくなるだろうが、それは危険な罠だ。膨大な数の図を作るよりも、さまざまな抽象化レベルでシステムを説明する、チームにとって本当に必要な2、3の図にこだわろう。そして、それらの図を常に更新しよう。図に詳細が多すぎず、タスクがチームのカルチャーの一部になると、これは簡単になる。
また、チームがアーキテクチャ図の一番の受益者であることを忘れてはいけない。彼らが興味を示さないなら、作るのをやめるべきだろう。時間の無駄になるかもしれない。包括的な手法に従うため、あるいは、アーキテクトとしての役割を正当化するために、ただ「存在していることを目的に」アーキテクチャ図を作成ってはいけない。
著者について
Ionut Balosin氏はLuxoftでソフトウェアアーキテクトを務めており、多種多様なビジネスアプリケーションにおいて10年以上の経験がある。パフォーマンスとチューニング、ソフトウェアアーキテクチャに関心がある。カンファレンスの常連スピーカーであり、テクニカルトレーナーでもある。