ソフトウェアアーキテクチャ図の描き方（2022）

 (terrastruct.com)
3 ポイント 投稿者 GN⁺ 2023-10-28 | 1件のコメント | WhatsAppで共有
  • 優れたアーキテクチャ図は、装飾よりも適切な抽象化レベル、最新性、曖昧さの排除によって、アイデアの伝達とコラボレーションを長く維持できるようにする
  • つながっている要素を近くに置く近傍距離の最小化が基本であり、図が大きくなるほど、消して描き直す反復が必要になる
  • 対称性は見た目の良い印象を作るだけでなく、入力と出力を別々の側に配置するような形で意味の伝達も強化する
  • 図形の中央揃えを保つと、複雑な概念もそれほど複雑に見えず、新しい要素を追加するときにも全体の配置が崩れにくい
  • ラベル付きのコンテナグループは、AWS と Azure のような環境の区分、ReaderWriter の実装のような抽象化、Cores のような関連オブジェクトのまとまりを一目で示す

長く残る図の条件

  • 優れた図は会議が終わった後も消されず、その後の議論や質問の基準点として使われ続けることができる
  • 長く使われる図には、いくつかの共通条件がある
    • 要素が適切な抽象化レベルにあること
    • 最新の状態を保っていること
    • 曖昧さがないこと
  • 同じエンティティと関係でも複数の描き方があるが、ある配置はプロジェクト期間中のコラボレーションを助け、別の配置は会議が終わると消えてしまう
  • ここでいう美しさは、影や角丸のような装飾ではなく、考えを効果的に伝える機能的な美しさである

読みやすい配置を作る原則

  • 近傍距離の最小化

    • 互いにつながっているノードは近くに描くのが基本である
    • 小さな図では簡単だが、図が大きくなり新しい接続が追加されるほど、この性質は崩れやすい
    • コードでエッジケースを見つけたら関連部分を直し、文書で抜けている項目を見つけたら文章を修正するように、文書用の図も必要なら消して描き直すべきである
    • 面接の場では描き直すコストが負担になり得るが、複数人や複数チームが使う文書であれば、反復的な修正がより良い図につながる

  • 対称性を見つける

    • 対称性は図の美的な印象に大きく寄与し、人間の脳は顔のような視覚的な対称性を好む傾向がある
    • すべてのノードが隣接ノードにできるだけ近くても、対称性が不足していると少し歪んだ図のように見えることがある
    • あるノードの近傍距離が少し伸びたとしても、対称性を合わせたバージョンのほうが見やすい場合がある
    • 入力を一方に、出力をもう一方に置く方法は、対称性とともに図の意味も強化する

  • 中央揃え

    • 整列は図をすっきり見せる大きな要素である
    • すっきりした図は概念をより明確にし、乱雑な図は概念をより複雑に見せる
    • 最初から空のキャンバスに図形をランダムに置くと、その後の配置もランダムになりやすい
    • 整列は2つ以上の図形の間でのみ意味を持つため、新しい要素を追加するたびに整列を保てば、図は自然にすっきりしていく
    • 対称性から整列が生まれる場合は多いが、必ずしもそうとは限らない

  • コンテナグループを使う

    • ラベル付きの複数の領域に図を分けると、見る人が構造をより理解しやすくなる
    • コンテナは図に次の情報を加えられる
      • 「これらのサービスは AWS にあり、これらのサービスは Azure にある」のように文脈を追加する
      • 「これらはすべて ReaderWriter の実装である」のように抽象化を示す
      • core 1、2、3、4 を「Cores」コンテナにまとめるように、関連オブジェクトをグループ化する

次回に続く項目

  • Part 2 では次のテーマが続く
    • エッジ経路の描画
    • ラベルのサイズと位置
    • 色
    • アイコン

関連記事

1件のコメント

 
GN⁺ 2023-10-28
Hacker Newsのコメント

  • D2で図を作るのをよく使っている。mermaid.jsに似ているが、書式設定のオプションが多く、個人的には構文もより良いと思う
    関連して短い記事も書いた: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • 図はきれいであるべきではないと感じる。たとえば色は美的・芸術的な選択ではなく、意味の伝達に使うべき
      見栄えの悪いソフトウェア図が見ていて楽しくないのは分かるが、装飾するのは折れ線グラフに曲線を入れるようなものだ。視覚的には良く見えても、伝えたいデータの邪魔になる
    • 例を試してみたところ本当に素晴らしかったが、案内とは違って左から右ではなく上から下にレンダリングされた
      最初の例 x -> y をSVGにレンダリングしてからSVGだけをブラウザで開き、出力の向きを変える方法をドキュメント全体で探したが見つからなかった
      ドキュメントの説明と実際の結果が違っていたので使うのをやめた。"d2lang connection left to right"で検索して https://d2lang.com/tour/layouts/ にたどり着いたが、概要ドキュメントからはリンクされていないようなので、反映すると訪問者の役に立つと思う
    • https://flowchart.fun/ は、システムプロセスを理解するためのフローチャートを非常に素早く描くのに役立った。直感的で高速に反復できる点が一番良く、スタイリング用のカスタムCSSもかなり便利だった
      フローチャートに限れば、これまで使ったテキストベースの図作成ツールの中で最も簡単で速い部類だと思う
    • D2には非常に優れたレイアウトエンジン talaがあるが、使うには有料ライセンスが必要だ。残り2つのエンジンはそれほど良くない
    • mermaidが好きでよく使っているが、D2も確認してみるつもり。宣言型ダイアグラムは、考えを読みやすい形で捉え、他のテキストと同じようにバージョン管理できる強力なツールだと思う

  • システムが変わり始めると、きれいな図は維持するのが非常に難しい。すでに複雑な図の真ん中に新しいボックスを追加することを考えると、すべてを再整列するのに1時間かかることもある
    2020年代の開発者の時間は、図をコードとして管理することに使ったほうがいい可能性が高い: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • 図作成の10%は実際に図を作る作業で、90%は矢印の整列だといつも冗談を言っている
      でも実際には冗談ではない気がする
    • structurizr.comに取り込んで表示するためのC4モデルを維持していたが、正直楽しくなかった。コードだけでは図から得られる直感的な理解や全体像が得られず、素早いローカルプレビューもないのでコードをサーバーにアップロードする必要があった
      さらに悪かったのは、新しいボックスを追加すると通常すべての矢印を再整列しなければならなかった点だ。その結果、図は継続的に最新の状態を保てなかった
      シーケンス図ではplantMLを使ったときのほうが良かった。作業自体がより簡単で、インタプリタの出力も通常は手動介入なしで十分使えた
    • 記事でも図を修正するのに時間が多くかかる点を扱っている。実際その通りで、標準化されたスキーマにきちんと従え、ツールが自動書式設定オプションを提供してくれると良いと思う
    • 要素を移動して再整列していると、図全体を学び直さなければならない。frobnitzがずっと右上にあったのに、配置上そのほうが良いという理由で突然左中央に移されたら、初めて見る人には役立つかもしれないが、6か月それを見てきた人にはまったく別物のように見える
      見栄えの悪いUIと似ている。見栄えが悪くても、使っている人たちはすでに慣れている。「整理」した瞬間に彼らのメンタルモデルを壊し、学び直させることになる
    • その時間投資に価値があるかどうかは、図の到達範囲と寿命に左右される
      ときには考えを整理するために、20分後に捨てるスケッチをするだけのこともある
      しかしオンボーディングや、他チームにシステムを説明するための参考資料なら、より理解しやすいものを作るのに費やした1時間は十分に報われる

  • こういうものを描くときはyEdを使っている。ボックスと矢印をめちゃくちゃにしても、メニューから数回クリックすれば自動で整えてくれる
    ただし妥協は必要だ。ボックス内のボックスは、いつも良い結果になるとは限らない。それでもはるかに速くドキュメント化でき、何度かやってみると何がうまくいき何がうまくいかないかの感覚がつかめるので、自分には良い折衷案だ

    • yEdは無料で使えるのか気になる。基盤となっているyWorks SDKは、Webサイト1つで開発者1人が使うだけでも5桁の金額がかかるようだ。20年近く顧客がいたなら、かなり強力なツールなのだろう
    • 同じように使っている。手で描く理由がない
      関係をTGFとして抽出して取り込み、階層型レイアウトを適用すればいい
      from, to, relation 形式で十分だ
    • 同じような理由でOmniGraffleを使っている

  • これには電気回路図、回路ダイアグラム、その他の工学図面との強い類似性がある。唯一の「正しい」方法はない
    コードと同じように、良い抽象化と表現方法を選ぶ能力が、理解可能なアイデアと後悔するような混乱を分ける。美しさや美学の問題ではなく、設計に能動的な思考と努力を必要とするツールだ

    • 抽象化レベルを一貫させるのは、ときどき本当に難しい。特にインフラ図では、異なるレベルの詳細をさらに入れたくなる衝動を抑えるのが難しい
      無限ズームアニメーションのように、図の中へ簡単にズームインしていけるツールがあるといい

  • まもなく https://VisualFlows.io v1.0 をリリース予定
    親会社の SaaS のアニメーション付き「アーキテクチャ」マップを数分で作れた: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    主な機能は Smart Sections、Smart Edges、Smart Node Deletion、ダーク/ライトモード、埋め込み、画像/SVG/GIF のドラッグ＆ドロップ、AWS/Windows/Google アイコン、来週予定の Markdown など
    Smart Sections について: https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • 同じ美的感覚を持つ、より成熟した https://whimsical.com ではなく、これを使う理由が何なのか気になる

  • この記事は本当に良かった。アーキテクチャ図を描くときでも、ドキュメントやコードを書くときでも、仕事で何かをするときには少し時間を取って「見栄えよく」しようとしている
    なぜそうするのか説明するのは難しいが、見た後のほうが気に入ることは分かっている
    それが時間の最も有効な使い方ではないのではと少し心配していたが、やめろと言われたことはない
    この記事が良いのは、勘でやっていたことを、何かをより美しくするための実践的な方法として説明してくれるところにある

    • 自分もこうしている。コーディングは自分にとってかなり視覚的な作業だ。「流れ」としか説明しにくい。コードに流れがないと満足できない
      コードの視覚的な感覚がないように見えるチームメンバーを見ると困惑する。関数の終わりと次の関数宣言の間に空行を入れなかったり、関数シグネチャで引数を1行に1つずつ書いたかと思えば複数個ずつ書いたりと一貫しない。自分の目には非常に目立つのだが、彼らは気にしていないようだ
    • 誰にも共有しないとしても、ページ上のブロックや要素の順序を考える過程そのものが、より大きな構造や依存関係について考えさせてくれる。ものすごく役に立つ
    • Visio でネットワーク図を作るときにも同じ感覚になる。Steve Jobs モードになって細かなディテールに執着する
      時間がかかることもあるが、何かが満たされる感じがある。自分に技術的なアートの才能がある程度あることは分かっていて、高校のころは製図工になりたかった
    • だからこそマークアップがある。非生産的な装飾から抜け出させてくれる。もちろんコーディングには当てはまらない
    • 「議論はこの図を中心に回る。人々は何気なく近づいて眺める。質問には図を指し示しながら答える。一日のうち定期的に椅子がこの中心物に向けて回され、人々は手を頭の後ろで組む。」
      まさに可視化の目的そのものだ

  • こういう用途には D2 が良い。以前の役割で、すべての serverless.yml ファイルをパースして巨大な D2 図を自動生成するプログラムを書いた
    AWS でマイクロサービスをやっていて、システムが大きくなるにつれて自動更新されるのが良かった。SNS topic を基準に分けるなど、各サブシステムごとの小さな図に分割できるようにした

    • draw.io も好き

  • 最初の例が理解できない。筆者は計画外のノードについて話しながら、実際には「I was unplanned」と名付けておいて、「事前に計画していたなら」と言っている
    図の文脈で計画外のものをどうやって事前に計画できるのか分からない。すべてのノードの周囲に十分な余白を残すべきという意味なのだろうか
    また、提案された改善案は「something」と「I was unplanned」が「engine」と相互作用するとき、同じチャネルやメカニズムを使っているように見せている

  • Miro を使っているが、高レベルの内容やアイデア出しには付箋ツールとしてかなり良い。ただし中レベルを超えるものではない
    コンポーネントやシステムが固まった後には、その作業にもっと適したツールがある

  • プロジェクトのドキュメントが Markdown なら、別のバイナリではなく ```plantuml ブロックを入れて図を埋め込めばよい
    GitLab ではブラウザで .md ファイルを見るときにきれいにレンダリングされる。GitHub にはまだその機能がない