johanhaleby/domain-storytelling

ドメインストーリーテリング

ドメインストーリーとは、文章として語られるビジネスプロセスの絵です。アクターが、ワークオブジェクトを使って何かを行い、時には別のアクターを関与させます。矢印上の数字が順序を示します。それ以外は順序を示しません。

このスキルはストーリーをモデル化し、レンダリングします。非自明なものをモデル化する前に、references/notation.md と references/spec.md を1回の呼び出しで読んでください。スペックファイルにはすべてのアイコン名がリストされています。

手順

1. ストーリーをモデル化します。 デフォルトはドラフトです：ユーザーが説明した内容から典型的なケースをモデル化し、アイコンを選択し、レンダリングし、自分が行った仮定を伝えます。選択がモデルを変更するのではなく装飾する場合にのみ質問してください。
2. 一度文章を読み返し、どのステップがオプションであるか、または時々異なる方法で発生するかを尋ねます。それらは注釈になります。これはスキップしやすいステップですが、スキップすると最もコストがかかります。なぜなら、表記法には分岐がないからです。時々しか発生しないステップは、注釈が付くか、暗黙のうちにハッピーパスに結合されます。
3. 代わりにワークショップを実施します。ユーザーがワークショップを要求した場合（/domain-storytelling workshop、「ワークショップを実施」、「これについて私にインタビュー」）、または計画が誰も文書化していないプロセスに依存している場合。今すぐ references/workshop.md を読んでください。インタビューと描画を同時に行わないでください。
4. スペックを記述し、レンダリングします。以下の「レンダリング」の説明に従ってください。
5. 警告に対処します。 ジェネレーターが stderr に何かを書き込んだ場合、今すぐ references/warnings.md を読んでください。ジェネレーターはそのファイル名を記載した行で終了するため、読み飛ばすと出力に現れます。
6. 画像を検査します。レンダリングが書き込んだプレビューPNGを読み、書き込まれたすべてのファイル名を伝えます。警告がなく、画像がクリーンにトレースされたときにレンダリングは完了です。

交渉不可のルール

これらはメソッドに由来するものであり、破るとドメインストーリーのように見えても実際にはそうではないものになります。

• すべてのアクターは正確に1回出現します。 アクターごとに1つの図形。それが何文に登場しても同じです。
• 異なる役割の2人は、ドメインがそれらを同じものと呼んでいても、2人のアクターです。 上記のルールは、1人のアクターが1回描かれることであって、1つの単語が1回描かれることではありません。同じ名詞の2つの言及をマージする前に、1人の人物が両方のステップを実行できるかどうかを尋ねてください。できない場合、それらは別々のアクターであり、それぞれがここで果たす役割を示す別々の図形と名前を持ちます。これを単に曖昧ではなく誤りにするのはシーケンス番号です。なぜなら、シーケンス番号は文5を実行するアクターが文2を実行したアクターであると主張するからです。分類のキューに参加し、駐車スペースを解放し、その後解放されたスペースを主張する1人の「ドライバー」は、ドライバーが駐車スペースを手放し、それを返してもらったと言っていますが、実際には出ていく保有者とキューに並ぶ者は役職は同じでも2つの役割です。誰か他の人がそのステップを実行できることを示す注釈（「管理者が代わりに駐車スペースを解放できる」）は、そのステップのアクターが確定していなかったことを示しています。
• すべてのアクティビティは、それ自身のワークオブジェクトを描画します。 3つの文で同じ注文は3つの図形です。これは重複ではなく、表記法が物事の移動を示す方法です。
• 条件分岐、分岐、ループはありません。 ゲートウェイ、ダイヤモンド、破線の「if」はありません。重要な代替案は別のストーリーとしてモデル化してください。小さなバリエーションは注釈として保持します。
• 文はアクターで始まり、シーケンス番号はその最初の矢印に付きます。2番目のアクターへの矢印には、数字ではなく前置詞が付きます。
• 同時に発生する文は1つの番号を共有し、任意の数の文が共有できます。スペック内でそれら全体にわたって同じ n の値を繰り返します。これが表記法で「同時に」を表現する唯一の方法です（フォークやジョインがないため）。一方が他方を本当に待つ場合ではなく、互いに待たないステップにはこれを積極的に使用してください。一方が他方に本当に続く場合は番号を別々に保ってください。共有番号は「これら2つは関連している」以上のことを主張するからです。
• ドメイン自身の言葉を使用します。 矢印上の動詞は、ドメインエキスパートが言った言葉です。「処理する」や「扱う」と書いている自分に気づいたら、まだそのステップを理解していないので、質問してください。コードから描かれたストーリーでは、ドメインの言葉は、人がトリガーするアクション、つまりボタン、エンドポイント、またはコマンドの名前です。したがって、cancel-reservation エンドポイントは「予約をキャンセルする」を作ります。各動詞は1つのアクションを指定し、1つのストーリー内の2つの異なるアクションは2つの異なる動詞を取得します。アクターに名前を付ける前に、そのエンドポイントを呼び出す画面に従い、その画面のユーザーにちなんでアクターに名前を付けてください。バックオフィスユーザーと管理エディタのエキスパートサービスは、異なることができる異なる役割だからです。隣接するアクションが同様の効果を持つ場合（駐車スペースの予約をキャンセルすることと、キューから待機者を削除すること）、注釈は画面とボタン、およびそれがではない隣接アクションを指定します。
• ワークオブジェクトは、ドメインがすでに言っている1つの名詞です。 「請求書」、「駐車スペース請求」。名前に and が含まれている場合は、それが2つであることを示しており、修正方法は、アクティビティが実際に動かす方を選ぶか、番号を共有する2つの文を書くことです。長さは症状であって欠陥ではないため、複合名を短くして収めると隠すだけになります。
• スコープを明確に述べてください。 粒度、時点、ドメイン純度。これらがないストーリーは、何を主張しているのかが曖昧です。これらは画像上ではなくスペックとEgonの説明に含まれます。なぜなら、これら3つの用語はメソッドがモデラーと対話するためのものであり、画像の読者はそれらを解読できないからです。

変更が及ぶ範囲の表示

ストーリーのポイントが変更がプロセスに与える影響である場合、変更が影響する文に "changed": true をマークし、その旨を説明に記述してください。差分がマークされた1つの画像は、読者が目で比較しなければならない2つの画像よりも通常は優れています。プロセスの形状が変更された場合（つまり、ステップがアクター間で移動したり、消えたりした場合）は、代わりにAS-ISストーリーとTO-BEストーリーを描画してください。ステップはそのままで内容だけが変更された場合はこの限りではありません。

変更が誰が何か（オファー、優先権、順番）を得るかを決定する場合は、対比を描画します。損失する人と得る人を、同じ役割でその立場によって名前が付けられた2人のアクターとして描画します（「最初の待機者」、「2番目の待機者」）。どちらがそれを得たかを示す文で終わります。その役割に1人のアクターしかいない場合、誰かを飛ばすルールは、何もしないルールとまったく同じように描画されます。

人からではなくコードから描かれたストーリーは、そのコードの読み取りです。その旨を画像の横に記載し、読者がその作業を行う誰かとチェックされていないことを認識できるようにします。変更された文を描画する前に、新しい動作が適用されるタイミングを決定するガード（必要な状態とそれを実行するイベント）を読んでください。そのイベントを変更の前の文として描画し、ストーリー全体が保持する状態（例：「出ていくドライバーはまだそこに駐車している」）を説明に含めてください。「次にキューが尋ねられたとき」のような注釈はアクターを指定しておらず、トリガーが見つからなかったことを示しています。

ストーリーの数

• 重要な代替案ごとに1つのストーリー。まずハッピーパスから。
• AS-IS と TO-BE は常に別々のストーリーであり、1つの画像にはしません。
• プロセスが大規模な場合、大まかな概要と、重要なステップのための1つの詳細なストーリー。
• 何であれ、約15文で分割します。広くて混雑した画像は、メソッドがストーリーが大きすぎると教えていることです。

セットとして読めるようにセットに名前を付けます：返金 - AS-IS、返金 - TO-BE。

レンダリング

スペックをJSONで記述し、この SKILL.md があるディレクトリからジェネレーターを実行します：

python3 scripts/story2egn.py path/to/story.json --preview <スクラッチディレクトリ>

標準ライブラリのみを使用します。スペックの隣、または --out-dir に2つのファイルを書き込み、--preview は独自のディレクトリに <Title>.png を追加するため、1回の呼び出しでストーリーをレンダリングし、画像を返して読むことができます。--preview は、出荷されるファイルから離れたスクラッチまたは一時ディレクトリを指定してください。PNGは、rsvg-convert、cairosvg、またはinkscapeがインストールされている場合はそれらから、そうでない場合はmacOSのクイックルックから生成されます。--help は他のフォーマットと --date をリストします。

• <Title>.egn.svg は、画像と編集可能なモデルを1つのファイルにまとめたものです。任意のSVGビューアで開き、https://egon.io にインポートできます。Egonはストーリータイトルをファイル名から読み取るため、スペック内のタイトルがファイル名を決定します。
• <Title>.board.svg は、ページ用の同じ画像です。すべてのアクター、ワークオブジェクト、アクティビティ、およびノートは、それが属するステップでタグ付けされたグループに配置され、それ自体のダークモードを持ちます。scripts/story-board.js は、1つのステップにディム、リング、またはクロップできます。egon.io で手描きされたボードにはタグがないため、プレーンな画像のままです。

常にユーザーに書き込まれたパスを伝えてください。ホストが画像を表示できる場合は画像をインラインで表示し、そうでない場合はパスが成果物です。ファイル名を指定せずにストーリーが生成されたと言ってはいけません。

ストーリーの読み返し

.egn、.egn.svg、およびレガシー .dst ファイルは、兄弟スキル egn-to-text によって読み取られます。ここで解析するのではなく、それを使用してください。