ブロック図を時間をかけて更新し維持するための最良のプラクティス

クリアで一貫性のあるビジュアルランゲージを維持

一貫性は認知負荷を低下させます。すべてのブロック図が同じシンボル、色、レイアウトルールを使用するとき、読者はすぐに認識を学習することなく意味を把握します。一方、一貫性は誤解を生む。

スタイルガイドの確立

定義する1ページスタイルガイドを作成します。

• ブロック形状 - たとえば、サービスのための長方形、俳優のための丸みのある長方形、決定のためのダイヤモンド。
• []Color Paltte] - 外部システム、内部の緑色、データストアの青のための赤を予約します。
• Line style] – 同期呼び出しの固形、非同期のハッシュ化、データフローの点字化
• []フォントとサイズ[] - 読みやすさのために10〜12ptで単一のサンスセリフフォントを使用します。
• [] ラベルの規則 - 常にブロック名と、複雑な図については、短い説明を含んでいます。

ガイドをすべてのコントリビューターに配布し、各図のメタデータにリンクを組み込む。ガイドの定期的なレビューは、進化するツール機能やチーム設定と一致させています。

細部を犠牲にしないで簡素化して下さい

ブロック図は、一度にすべてを表示しようとすると、乱雑になることができます。 階層ビューに大きなシステムを破る:ハイレベルな概要図は、レベルの詳細図に接続します(例えば、「コンピュートレイヤー」は、コンテナとロードバランサのサブレベルのdiagramに拡大します)。 数値化された参照またはハイパーリンク(デジタルフォーマット)を使用して、レベル間の移動します。 このレイヤードアプローチは、単一の図を防止しながら、精度を維持し、単一の図がボックスと線の側面になるようにします。

フィードバックをアップデートサイクルに組み込む

図は、エンコードする情報としてのみ適しています。システムを構築し、運営する人々は、最も新鮮な知識を保持します。入力を収集するためのルーチンを確立します。

連続フィードバックの文化を醸し出す

チームメンバーは、プロジェクトトラッカーの専用のSlackチャンネルや問題テンプレートなど、単純なプロセスで修正や提案を提出します。週単位または週単位でコントリビューションをレビューします。すべての提案が採用されるわけではありませんが、すべてのコントリビューションが所有権を把握し、早期にミスをキャッチします。スプリントアウト中の「diagram walkthrough」またはポストインシデントレビューでこれにペアリングすると、現在の図は実際のシステムと比べています。

可能であれば自動検証

いくつかの図形環境では、基本的な検証ルールをサポートしています。例えば、すべてのブロックにラベルが付いて、2つのブロックが同じ名前を共有していないことを強制することができます。限られた間、これらのチェックは、図が聴衆に到達する前に、共通のエラーをキャッチします。高度なニーズのために、スクリプトは、図のソースファイルを解析し、システム在庫に対するブロック名を比較し、欠落または廃止されたコンポーネントをフラグを立てることができます。

適切なツールとテンプレートを選択します。

簡単に更新できる方法と、一貫した図が維持される方法に影響するツール。チームサイズ、コラボレーションニーズ、既存のワークフローとの統合に基づくオプションの評価。

ソフトウェアオプション 比較

• [Microsoft Visio] - エンタープライズ環境に強力で、複雑な形状とデータ連携をサポートしています。ほとんどのチームメンバーがWindows上でいるとき、最高です。
• [Lucidchart] – クラウド・ファースト、リアルタイムコラボレーション、広範な形状ライブラリ。 ドキュメントワークフローのConfluenceとJiraを統合します。
• [draw.io(diagrams.net)[] - 自由で、オープンソース - オフライン編集と多くのエクスポートフォーマットをサポートしています。 純粋なXMLに保存しているため、Gitでうまく動作します。
• [PlantUML/マーメイド[ – テキストベースの図生成。バージョン管理図をコードとしてしたいチームに最適ですが、視覚的な上向きが少ない。

ツールは、あらゆる状況で完璧です。 実際にチームを使用するものを選ぶ。 未使用のツールは、単純なホワイトボードの写真よりも悪くなります。 選択したら、スタイルガイドを埋め込む再使用可能なテンプレートを作成する時間に投資します。これにより、新しい図を始動させ、最初のブロックから一貫性を強化する障壁が低下します。

長期メンテナンス:レビュー、ドキュメント、トレーニング

長年にわたって図を常緑化し続けるには、アドホックの更新が必要です。チームのリズムに織り込まれた体系的なアプローチが必要です。

定期レビューのスケジュール

各図を見直して、カレンダーリマインダーを設定します。周波数はシステムの変更率によって異なります。高速移動マイクロサービスアーキテクチャの場合、2週間ごとに適切な状態にすることができます。安定したレガシーシステムの場合、四半期ごとに十分です。レビュー中に、次の質問をしてください。

• あらゆるブロックは、生産中に存在しませんか?
• 接続(データフロー、依存関係)は、まだ正しいですか?
• 命名規則は変更されますか?
• 新たに追加すべきコンポーネントはありますか?

変更が不要になった場合でも、各レビューの結果を文書化し、監査のデューデリジェンスを証明する。

トレーサビリティによる文書変更

単純な変更ログを超えて、図表の更新を特定のシステムの変更にリンクします。例えば、図版を解放ノートや機能チケットに添付します。このトレーサビリティは、図がその方法を見て、監査人がデプロイされたシステムとドキュメントの整列を検証することを可能にする理由を理解するのに役立ちます。 Notion]のようなツールを使用して、または、ドキュメントページに直接図を埋め込むためのConfluence、それが更新されたときに表示されるバージョン履歴ウィジェットで。

ダイアグラムメンテナンスにおけるチームメンバーのトレーニング

図を更新する方法の知識は、シロエードされるべきではありません。選択したツール、スタイルガイド、および更新ワークフローに関する短いトレーニングセッションを実行します。 重要なアクション(ブロックの追加、保存、エクスポート、ドキュメントへのリンク)をカバーする[quick-start guideを作成します。 ペアニューは、最初の数回のアップデートで図「buddy」で採用します。 目標は、変更を繰り返すための決定的な努力を下げることです。 誰が、それをすぐに更新することができます。

オートメーションと統合の機会

手動メンテナンスは不十分です。更新プロセスの部分を自動化する機会を探します。例えば、コードとしてインフラストラクチャを使用する場合、スクリプトはAWS CloudFormation または Terraform ステートファイルを解析し、自動的に図案を生成することができます。自動生成された図は、人間のポーランドを必要とするが、それらは手動ブロック配置の時間を節約します。CI/CD パイプラインとの統合は、各展開後に新鮮な図を作成したり、意図されたアーキテクチャと実行システム間のドリフトをフラグしたりすることもできます。

よりシンプルな自動化でも役立ちます: ツール API を使用して、エクスポートされた図にタイムスタンプまたはバージョンバッジを追加したり、図が3か月で触れていないときにリマインダーを送信したりする cron ジョブをセットアップしたりできます。

コンテンツ

ブロック図は、生きた文書です。 努力を怠らず、彼らはノイズに衰退します。 バージョンコントロールを採用することにより、視覚的な一貫性を強化し、フィードバックを埋め、適切なツーリングを選択し、チームルーチンにメンテナンスを埋め込むことで、あなたの図は真実の信頼できるソースのままであることを保証します。 懲戒更新プロセスの小さな投資は、少数の誤解、迅速なトラブルシューティング、およびより自信のある決定で返済します。 御馳走図は、あなたのシステムと一緒に、その資産の段階を進化させないが、あなたのシステムと同じくらい進化する。