11章は「アーキテクチャを記述する」章で、ソフトウェアアーキテクチャの文章化を上手におこなって、見る人の関心事に着目したアーキテクチャ記述を学ぶ章でした。
この章で伝えたいことを整理する
まずはアーキテクチャの文章化のメリットデメリットについて述べられています。 デメリットは、アーキテクチャを文章化している分コードを書く時間が減ることや、メンテナンスされずに実物と文章がこなるアーキテクチャになることが挙げられていました。 もちろんメリットもあり、ビジョンが伝わり一貫性を保ちやすくなったり、設計計画を立てやすくなることがあります。
メリットとデメリットはわかりましたが、それを踏まえて必要な理由は何でしょうか。 それはコンポネント同士の結びつきや振る舞いを整理することや、ステークホルダー間の共通語を確立できるためです。 自分はこの共通語というところがDDDにおけるユビキタス言語に近しい文脈のように感じました。 仕様書通りに作ることはもちろん大切ですが、ステークホルダーが置き去りになることなく共に作り上げるニュアンスが含まれていると感じました。
様々なシチュエーションで必要になってくるため、それに応じた記述方法を選ばなくてはなりません。 本の中では、変更が「簡単」「難しい」か、共有が「簡単」「難しい」の2軸で考えることを勧めていました。 この部分でも気に入ったものがあり、それは変更が難しく、共有も難しい「無駄な方法」と述べられていた部分です。 その方法はスライドによるアーキテクチャ記述で、スライドだけでは独立できないこと（=共有が難しい）と、スライドの位置や参照を調整するのが大変といったこと（=変更が難しい）の2つを挙げられていました。 ついついスライド作成ツールを使って見栄えを良くしたほうがいい感覚になりますが、上記で述べられているようなことを感じ最近は使用していません。 アイデアの共有だけだったらまずはマークダウンファイルで良いわけですし、このなかでもリストや強調と行ったことを駆使して表現できます。 またテキストファイルなのでツールや環境にも大きく左右されません。
他には聴衆に配慮するといったことが述べられていますが、要は受け手を意識して共有しようということです。 我々エンジニアは日々難しい用語などを正しく使おうとしています。 コレ自体は全く悪くないことですが、やはり普段ITに携わらない人からすると理解がしにくいものです。 なので、なるべくステークホルダーと同じ言葉を使い専門用語を避けたり、背景知識が必要なものも簡単に定義したりしましょうということです。 また図や表を使う場合も凡例を使い理解しやすいように努めましょうということが述べられていました。
最後に個人的に良かったと思うところは、判断の論理的根拠を説明するです。 設計の根拠が伝わることでアーキテクチャの一貫性が保たれるという当たり前のことが書かれていましたが、自分に響いたのは次の文脈でした。 それは、選ばなかった案についても言語化するということです。 この部分を言語化しておくと、設計判断に耐え地会えなかった人にも納得感が与えられるのと、不要な議論を避けられるのが挙げられていました。 ドキュメント化するときには、自分たちが通ってきた道ばかりを残してしまいそうですが、分かれ道で選ばなかった方も「なぜ選ばなかったか」を記述しておくと、他の人の共有も楽になることを学べました。
