diagramming-processes

プロセスの図解

前提として必須: technical-writing スキル(ハードルール、真実ルール、スタイル)。

概要

図とは、文章の代わりに描かれた一連の主張です。すべてのボックスと矢印は、文と同じ真実ルールに拘束されます。中心原則は、振る舞い(プロセス、ライフサイクル、相互作用)を図解し、ソースをバージョン管理下に置き、すべてのレンダリング結果を派生物として扱うことです。文章は、文章が苦手とするもの、つまり分岐、並行性、状態を所有します。

いつ呼び出すか、呼び出さないか

フロー、ライフサイクル、相互作用を示す必要があるときに呼び出します。コンポーネントや組織をまたぐビジネスプロセス、状態機械、メッセージ交換、レガシーキャンペーンの processes.md(documenting-legacy-codebases)などです。装飾のために呼び出してはいけません。3～4ステップの線形な流れは番号付きリストであり、それを言い換えるだけの図は飾りです。対象外: データから生成されるチャート(メトリクス、トレンド)と、実装構造です。後者は以下の振る舞いルールが禁じています。

記法のはしご

描く前に高度を定め、それに記法を合わせます。

• ビジネス層: ArchiMate。 部門、組織、または複数のシステムをまたぐプロセス、ケイパビリティマップ、そしてエンタープライズのステークホルダーが期待する TOGAF スタイルのビューです。読み手は役割、サービス、プロセスを読み、コンポーネントは決して読みません。
• システム層: PlantUML の振る舞い図。 システム内およびシステム間のフロー、状態機械、シーケンスです。コードドキュメントであり、コードより1レベル上です。
• コード層: 図はなし。 クラスとパッケージの構造はコード自身が示すものです。IDE は、コミットされたどんな図よりも新しい絵をオンデマンドで生成します。

このはしごが定めるのは記法と語彙であり、ツールではありません。PlantUML は標準ライブラリで ArchiMate 記法を扱えるため、1つのツールチェーンで両方の段を担えます。リポジトリが使うツールは、「絵ではなくソース」の下で一度だけ決めます。

絵ではなくソース

• ソースはコミットされたテキストであり、リポジトリがすでに使っている図ツールで記述します。何も確立されていない場合、デフォルトは PlantUML です(豊富な標準ライブラリ、ArchiMate を含む)。選択が本当に自由な場合は、オーナーに確認し、PlantUML を推薦します。中核スキルの references/truth.md が基本ルールを所有します。レンダリング結果は派生物であり、古くなったレンダリング結果は誤解を招くために残すのではなく削除します。
• 1つのソースファイルにつき1つの図とし、示すプロセスにちなんで命名し、ドキュメントの隣の1つの diagrams ディレクトリにまとめます。
• レンダリングにはリポジトリが所有するツール(スクリプト、make ターゲット、またはビルドステップ)が必要で、図の作者ではなくオーナーが設定します。欠けている場合はオーナーに伝えます。ホスティングプラットフォームがたまたまインラインでレンダリングする記法を選んで、このギャップを回避してはいけません。
• 1つのリポジトリコマンドですべてをレンダリングします。ホストがすでにリポジトリの選択したソース形式をレンダリングする場合を除き、レンダリング結果はコミットします。ソースが変わったら、古くなったレンダリング結果は同じ変更で削除し、再生成されるまで欠落したレンダリング結果をインデックスに記録します。
• ソースのないスクリーンショット、エクスポートされた画像、またはホワイトボードの写真は、それを含むドキュメントに対する指摘事項です。誰も diff を取れないため、誰も保守しません。

種類は読み手の問いに答える

読み手が持ち込む問いから種類を選び、1つの図につき1つの問いにします。

読み手の問い	描くもの
このプロセスは組織全体でどのように実行されるか	ArchiMate ビジネスプロセスビュー
何が、どの順序で、どの判断を伴って起こるか	アクティビティ図
このものはどの状態を取り得て、何がそれを移行させるか	状態機械
誰が誰と、どの順序で、どのメッセージで会話するか	シーケンス図
このドメインに何が存在し、それがどう関係するか	概念図、ビジネスオブジェクトレベルで

2つの問いに答える図は、どちらにも答えていません。分割してください。独自に発明した記号の凡例を必要とする図は、一度にあまりに多くに答えています。

振る舞いを記述し、実装には踏み込まない

documenting-legacy-codebases のリファクタリングテストは図にも当てはまります。そして図は、段落よりももうまくそのずれを隠します。

• 参加者はシステム、役割、モジュール、ビジネスオブジェクトです。 クラス、メソッド、関数はコードの中にとどまります (はしごを参照)。
• エッジは、そのドメインの言葉でイベントまたは条件を運びます:「支払い確認済み」であり、コールバック名では決してありません。ガードは設定キーを名指ししてもかまいません。設定キーは契約の表面だからです。しかしメソッドを名指しすることは決してありません。
• タイトルはプロセスを名指しします。仕様、フェーズ、計画を決して名指ししません。配信ナラティブ禁止のハードルールは、コメントを含め、図のソースの中でも適用されます。
• エラーと例外の経路は、振る舞いが異なる箇所に描かれ、区別できるように描かれます。実際の失敗分岐を持つプロセスのハッピーパスだけの図は、誇張された主張です。
• クセは描かれ、そしてそれは内容です。 何も抜け出せない状態、ある入力に対してだけステップを飛ばすフロー。驚くべき分岐こそが、その図が存在する価値の理由です (documenting-legacy-codebases、クセ)。

図のインデックス

5 つを超える図には、そのそばに 1 つのインデックスドキュメントが付きます。これはファイルから再構築される派生成果物です (中核となる真実のルール)。

• カバレッジ表: 各図が何を示すか、そのソースファイル、コミットされている場合はそのレンダリング、そしてそのステータス。
• 図ごとに、それが記述するモジュールを、ずれのアンカーとして示します。図がコードを指す唯一の場所です。
• レンダリングコマンド。これにより、インデックスはビルド手順にもなります。
• 保留中のレンダリングをソースごとに名指しすることで、欠けているレンダリングは黙った抜けではなく、追跡された状態になります。

メンテナンス

フローを変える変更は、同じ変更の中で対応する図のソースを更新します。図はドキュメントであり、ドキュメントは完了の一部です (中核となる真実のルール)。レンダリングは図のコンパイルステップです。ソースの編集は構文を目に見えない形で壊し、その破損はレンダリングが実行されたときに初めて表面化します。編集を出荷する前に著者がレンダリングします。リポジトリのパイプラインがまだ整っていない場合は、ツールをローカルで一度だけ実行すればこのチェックを満たします。機能が削除されるときは、1 つの変更が散文、図のソース、インデックスの行、コミットされたレンダリングをカバーします。誰も更新しようという気になれない図は、大きすぎる問いに答えています。独立して変化する継ぎ目に沿って分割してください。

検証

図の中で読み取れるものはすべて主張です (中核となる真実のルール)。したがって、図は散文と同じように根拠づけられ、レビューされます。

• 著者は、描く前にすべてのボックス、矢印、ガードをコードに対して検証します。確認されるのではなく推測されたフローは、埋め込み先のドキュメント内で図のそばに推測であるとラベル付けされます。事実として黙って描かれることは決してありません。
• レビュアーは、振る舞いに対して図を読み、絵ではなくソーステキストをレビューします。ソースこそが、次の編集者が変更するものだからです。
• 図のソースは散文と同じようにずれ、すべてのレガシーキャンペーンに加わります。キャンペーン (documenting-legacy-codebases) は、図のソースを、それらを埋め込むドキュメントとともに根拠づけます。
• 図とその周囲の散文は、事実ごとに 1 つの家を共有します。散文はプロセスがなぜ存在するか、何に注意すべきかを述べ、図はフローを示し、どちらも他方をステップごとに繰り返しません。