johanhaleby/domain-storytelling

領域故事（Domain Storytelling）

領域故事是以句子形式呈現的業務流程圖：某個角色對某個工作物件做了某件事，有時涉及另一個角色。箭頭上的數字表示順序，除此之外沒有其他順序指示器。

此技能會對故事進行建模，然後將其渲染出來。在建模任何非平凡案例之前，請先在一次呼叫中閱讀 references/notation.md 和 references/spec.md。規格檔案列出了所有圖示名稱。

步驟

1. 建立故事模型。 預設使用草稿模式：根據使用者描述的典型情況建模、選擇圖示、渲染，並說明您做了哪些假設。僅在選擇會改變模型（而非僅是裝飾）時才提問。
2. 將句子讀回一遍，並詢問哪些是可選的，或者在某些情況下會有所不同。這些將成為註解。這是最容易被跳過的步驟，而跳過它的成本最高，因為記號法沒有分支。一個僅在某些時候發生的步驟，要嘛帶有註解，要嘛默默地合併到快樂路徑中。
3. 當使用者要求工作坊時，改為執行工作坊（/domain-storytelling workshop、「執行工作坊」、「就此訪談我」），或者當計劃依賴於從未記錄下來的流程時。立即閱讀 references/workshop.md。切勿同時訪談和繪圖。
4. 撰寫規格並進行渲染，如下方「渲染」所述。
5. 處理警告訊息。 當生成器將任何內容寫入 stderr 時，立即閱讀 references/warnings.md。生成器會以一行命名該檔案的名稱結尾，因此跳過閱讀會顯示在輸出中。
6. 檢查圖片，方法是閱讀渲染器寫入的預覽 PNG，並列出所有寫入的檔案。當渲染結果沒有警告且圖片路徑清晰可追蹤時，即完成渲染。

不可協商的規則

這些規則源自該方法，違反它們會產生看似領域故事但實際並非如此的產出。

• 每個角色僅出現一次。 每個角色一個形狀，無論它出現在多少個句子中。
• 不同角色的兩個人是兩個不同的角色，即使領域中他們被稱為同一事物。 上述規則是指一個角色只畫一次，而不是一個詞只畫一次。在合併同一名詞的兩個提及之前，請詢問一個人是否可以執行這兩個步驟。當不能時，它們就是不同的角色，應有各自的形狀和名稱，以說明每個角色在此扮演的職責。順序編號之所以會讓這個錯誤不僅僅是模糊，是因為它們斷言執行句子 5 的角色就是執行句子 2 的那個角色。一個加入分類佇列、釋放停車位、然後認領釋放車位的單一駕駛，意味著一個駕駛放棄了停車位又拿回它，而實際上離開的持有者和排隊者是兩個共享同一個職稱的角色。一個說明其他人可以執行此步驟的註解（例如「管理員可以代替釋放停車位」），就是該步驟的角色從未確定的跡象。
• 每個活動都繪製自己的工作物件。 三個句子中的相同順序就是三個形狀。這不是重複，而是記號法顯示事物移動的方式。
• 沒有條件判斷、分支或迴圈。 沒有閘道器、菱形或虛線的「如果」。重要的替代方案應建模為單獨的故事。小變化則保留為註解。
• 句子以一個角色開頭，順序編號放在該第一個箭頭上。連接到第二個角色的箭頭則帶有介詞，而非數字。
• 同時發生的句子共享一個編號，且任意數量的句子都可以。在規格中跨它們重複 n 值。這是記號法中表示「同時」的唯一方式，因為它沒有分叉和合併，所以在任何一個步驟不等待另一個步驟時都應使用它。當一個步驟確實緊跟在另一個步驟之後時，請保持編號分開，因為共享編號所斷言的不僅僅是「這兩個是相關的」。
• 使用領域自身的語言。 箭頭上的動詞應是領域專家所使用的詞語。如果您發現自己寫了「處理」或「管理」，代表您尚未理解該步驟，請提問。在從程式碼繪製的故事中，領域的詞語是人觸發的動作名稱，即按鈕、端點或命令，因此 cancel-reservation 端點對應的是「取消預約」。每個動詞命名一個動作，一個故事中的兩個不同動作應使用兩個不同的動詞。在命名角色之前，請先跟隨端點到呼叫它的畫面，然後以該畫面的使用者來命名角色，因為後台使用者和管理編輯器中的專家服務是不同的角色，可以執行不同的事情。當相鄰動作具有類似效果時（例如取消停車位預約與從佇列中移除排隊者），備註應說明畫面與按鈕，以及它不是的相鄰動作。
• 工作物件是領域中已使用的一個名詞。 例如「發票」、「停車位認領」。名稱中包含 and 表示它是兩個東西，修復方法是選擇活動真正移動的那一個，或者寫兩個共享編號的句子。長度是症狀而非錯誤，因此縮短複合名稱以適應只會掩蓋問題。
• 明確說出範圍。 包含粒度、時間點、領域純粹性。沒有這些的故事，對於它所斷言的內容是模糊的。範圍會伴隨規格和 Egon 描述，而非顯示在圖片上，因為這三個術語是方法與建模者之間的對話，而圖片的讀者無法解讀它們。

顯示變更的落點

當故事的重點是變更對流程的影響時，將受影響的句子標記為 "changed": true，並在描述中說明。一張標記了變更範圍的圖片，通常勝過兩張需要讀者肉眼比對的圖片。當流程的形狀改變（即步驟在角色之間移動或消失），而不是步驟保持不變僅內容改變時，則應分別繪製 AS-IS 和 TO-BE 故事。

當變更決定誰獲得某物（例如一個提議、優先權或輪次）時，請繪製對比：損失方與獲得方，作為相同角色中的兩個不同角色，以其位置命名（例如「第一位排隊者」、「第二位排隊者」）。以說明誰獲得了它的句子結束。若該角色只有一個角色，則跳過某人的規則繪製出來就像什麼都沒做的規則一樣。

從程式碼而非從人繪製的故事，是對該程式碼的解讀。請在圖片旁邊說明這一點，以便讀者知道它未經任何實際執行工作的人確認。在繪製變更後的句子之前，請閱讀決定新行為何時適用的守衛條件：它所需的狀態以及觸發它的事件。將該事件繪製為變更前的句子，並將整個故事所持有的狀態（例如「離開的駕駛仍停在那裡」）放入描述中。像「下次佇列被詢問時」這樣的備註沒有命名任何角色，是觸發條件從未找到的跡象。

故事數量

• 每個重要的替代方案一個故事。首先是快樂路徑。
• AS-IS 和 TO-BE 始終是單獨的故事，從不共用一張圖片。
• 當流程較大時，一個粗略總覽加上一個針對關鍵步驟的詳細故事。
• 無論其他情況如何，大約每十五個句子就要拆分。一張寬闊、擁擠的圖片是方法告訴您故事太大的信號。

命名一組故事使其看起來像一組：Refund - AS-IS、Refund - TO-BE。

渲染

以 JSON 格式撰寫規格，然後從包含此 SKILL.md 的目錄執行生成器：

python3 scripts/story2egn.py path/to/story.json --preview <暫存目錄>

僅使用標準函式庫。它會在規格旁邊寫入兩個檔案，或者寫入 --out-dir 指定的目錄，而 --preview 會在一個獨立目錄中新增 <Title>.png，因此一次呼叫即可渲染故事並傳回圖片供閱讀。請將 --preview 指向暫存或臨時目錄，遠離要交付的檔案。PNG 來自 rsvg-convert、cairosvg 或 inkscape（當其中一個已安裝時），否則來自 macOS 的 Quick Look。--help 會列出其他格式和 --date。

• <Title>.egn.svg 是圖片和可編輯模型合而為一。它可以在任何 SVG 檢視器中開啟，並可在 https://egon.io 匯入。Egon 會從檔案名稱中讀取故事標題，因此規格中的標題決定了檔案名稱。
• <Title>.board.svg 是適用於頁面的相同圖片。每個角色、工作物件、活動和備註都放置在以所屬步驟標記的群組中，並自帶暗色模式。scripts/story-board.js 可以淡化、圈選或裁剪到一個步驟。在 egon.io 上手繪的板子沒有標籤，因此保持為純圖片。

始終告知使用者所寫入的路徑。如果主機可以顯示圖片，則將圖片內嵌展示；否則路徑即為交付物。切勿在未命名檔案的情況下聲稱生成了故事。

讀回故事

.egn、.egn.svg 和舊版的 .dst 檔案由同級技能 egn-to-text 讀取。請使用該技能，而非在此解析它們。