johanhaleby/domain-storytelling

Domain Storytelling

Eine Domain Story ist ein Bild eines Geschäftsprozesses, erzählt in Sätzen: Ein Akteur tut etwas mit einem Arbeitsgegenstand, manchmal unter Beteiligung eines anderen Akteurs. Die Zahlen auf den Pfeilen tragen die Reihenfolge. Nichts anderes tut dies.

Diese Fertigkeit modelliert die Geschichte und rendert sie dann. Lies references/notation.md und references/spec.md in einem einzigen Aufruf, bevor du etwas Nichttriviales modellierst. Die Spezifikationsdatei listet jeden Symbolnamen auf.

Schritte

1. Modelliere die Geschichte. Entwurf ist der Standard: Modelliere den typischen Fall basierend auf der Beschreibung des Benutzers, wähle Symbole aus, rendere und sage, welche Annahmen du getroffen hast. Frage nur, wenn eine Entscheidung das Modell verändern würde und nicht nur verzieren.
2. Lies die Sätze einmal zurück und frage, welcher davon optional ist oder manchmal anders abläuft. Diese werden zu Annotationen. Dies ist der am einfachsten zu überspringende Schritt, und das Überspringen kostet am meisten, da die Notation keine Verzweigungen hat. Ein Schritt, der nur manchmal vorkommt, trägt entweder eine Annotation oder schließt sich stillschweigend dem Happy Path an.
3. Führe stattdessen einen Workshop durch, wenn der Benutzer danach fragt (/domain-storytelling workshop, "führe einen Workshop durch", "interview mich dazu") oder wenn ein Plan von einem Prozess abhängt, den niemand dokumentiert hat. Lies jetzt references/workshop.md. Interview niemals und zeichne gleichzeitig.
4. Schreibe die Spezifikation und rendere sie wie im Abschnitt Rendern unten beschrieben.
5. Reagiere auf die Warnungen. Wenn der Generator etwas auf stderr schreibt, lies jetzt references/warnings.md. Der Generator endet mit einer Zeile, die diese Datei benennt, sodass ein übersprungenes Lesen in der Ausgabe sichtbar ist.
6. Überprüfe das Bild, indem du die vom Renderer geschriebene Vorschau-PNG liest und jede geschriebene Datei benennst. Ein Rendervorgang ist abgeschlossen, wenn er keine Warnungen enthält und das Bild sauber nachvollziehbar ist.

Nicht verhandelbare Regeln

Diese stammen aus der Methode, und ein Verstoß erzeugt etwas, das wie eine Domain Story aussieht, aber keine ist.

• Jeder Akteur erscheint genau einmal. Eine Form pro Akteur, egal in wie vielen Sätzen er vorkommt.
• Zwei Personen in unterschiedlichen Rollen sind zwei Akteure, selbst wenn die Domäne sie gleich nennt. Die obige Regel bezieht sich darauf, einen Akteur einmal zu zeichnen, nicht darauf, ein Wort einmal zu zeichnen. Bevor du zwei Nennungen desselben Substantivs zusammenführst, frage, ob eine Person beide Schritte ausführen könnte. Wenn nicht, sind es separate Akteure, und sie erhalten separate Formen und Namen, die die Rolle angeben, die jeder hier spielt. Die Sequenznummern machen dies eher falsch als nur vage, da sie behaupten, dass der Akteur, der Satz 5 ausführt, derselbe ist, der Satz 2 ausgeführt hat. Ein einzelner Fahrer, der in die Warteschlange einer Klassifikation eintritt, einen Parkplatz freigibt und dann den freigegebenen Platz beansprucht, sagt aus, dass ein Fahrer einen Parkplatz aufgegeben hat und ihn zurückbekam, während der abfahrende Halter und der Warteschlangensteher zwei Rollen sind, die denselben Jobtitel teilen. Eine Annotation, die jemand anderen benennt, der den Schritt ausführen könnte, "ein Administrator kann stattdessen den Parkplatz freigeben", ist der Hinweis darauf, dass der Akteur des Schritts nie festgelegt wurde.
• Jede Aktivität zeichnet ihren eigenen Arbeitsgegenstand. Dieselbe Bestellung in drei Sätzen sind drei Formen. Dies ist keine Duplizierung, sondern die Art und Weise, wie die Notation die Bewegung des Dings zeigt.
• Keine Bedingungen, Verzweigungen oder Schleifen. Es gibt kein Gateway, keine Raute, kein gestricheltes "wenn". Modelliere eine wichtige Alternative als separate Geschichte. Behalte eine kleine Abweichung als Annotation bei.
• Ein Satz beginnt mit einem Akteur und die Sequenznummer gehört zu diesem ersten Pfeil. Der Pfeil zu einem zweiten Akteur trägt eine Präposition, keine Nummer.
• Sätze, die gleichzeitig stattfinden, teilen sich eine Nummer, und es können beliebig viele sein. Wiederhole den n-Wert in der Spezifikation für alle. Dies ist die einzige Möglichkeit, mit der Notation "gleichzeitig" auszudrücken, da sie weder Gabel noch Zusammenführung hat. Greife also immer dann darauf zu, wenn kein Schritt auf den anderen wartet. Halte die Nummern getrennt, wenn einer dem anderen wirklich folgt, denn eine gemeinsame Nummer behauptet mehr als "diese beiden sind verwandt".
• Verwende die eigenen Wörter der Domäne. Das Verb auf dem Pfeil ist das Wort, das der Domänenexperte gesagt hat. Wenn du dich dabei ertappst, "verarbeitet" oder "handhabt" zu schreiben, hast du den Schritt noch nicht verstanden, also frage nach. In einer aus Code abgeleiteten Geschichte ist das Wort der Domäne der Name der Aktion, die eine Person auslöst, der Button, Endpunkt oder Befehl, also macht ein cancel-reservation-Endpunkt "storniert die Reservierung". Jedes Verb benennt eine Aktion, und zwei unterschiedliche Aktionen in einer Geschichte erhalten zwei unterschiedliche Verben. Folge dem Endpunkt zu dem Bildschirm, der ihn aufruft, bevor du den Akteur benennst, und benenne den Akteur nach den Benutzern dieses Bildschirms, denn ein Backoffice-Benutzer und ein Expert Service im Admin-Editor sind unterschiedliche Rollen, die unterschiedliche Dinge tun können. Wenn eine benachbarte Aktion eine ähnliche Wirkung hat, das Stornieren einer Parkplatzreservierung im Gegensatz zum Entfernen des Warteschlangenstehers aus der Warteschlange, dann nennt die Notiz den Bildschirm und den Button sowie die benachbarte Aktion, die es nicht ist.
• Ein Arbeitsgegenstand ist ein einzelnes Substantiv, das die Domäne bereits verwendet. "Rechnung", "Parkplatzanspruch". Ein und im Namen ist der Hinweis darauf, dass es zwei sind, und die Lösung besteht darin, denjenigen auszuwählen, den die Aktivität wirklich bewegt, oder zwei Sätze mit gemeinsamer Nummer zu schreiben. Länge ist das Symptom und nicht der Fehler, daher verbirgt eine Verkürzung eines zusammengesetzten Namens, um ihn anzupassen, das Problem nur.
• Sage den Umfang laut. Granularität, Zeitpunkt, Domänenreinheit. Eine Geschichte ohne diese Angaben ist mehrdeutig darüber, was sie überhaupt behauptet. Dies wird in der Spezifikation und in der Egon-Beschreibung transportiert, nicht im Bild, weil diese drei Begriffe die Methode sind, die mit dem Modellierer spricht, und ein Leser des Bildes sie nicht entschlüsseln kann.

Anzeigen, wo eine Änderung landet

Wenn der Punkt der Geschichte ist, was eine Änderung mit einem Prozess macht, markiere die Sätze, die sie berührt, mit "changed": true und sage dies in der Beschreibung. Ein Bild mit markiertem Delta ist in der Regel besser als zwei Bilder, die der Leser visuell vergleichen muss. Zeichne stattdessen eine AS-IS- und eine TO-BE-Geschichte, wenn sich die Form des Prozesses geändert hat, d.h. Schritte zwischen Akteuren verschoben wurden oder verschwunden sind, und nicht, wenn die Schritte an Ort und Stelle blieben und sich nur ihr Inhalt änderte.

Wenn die Änderung entscheidet, wer etwas bekommt, ein Angebot, eine Priorität oder eine Reihe, zeichne den Kontrast: die Person, die verliert, und die Person, die gewinnt, als zwei Akteure in derselben Rolle, benannt nach ihrer Position ("Erster Warteschlangensteher", "Zweiter Warteschlangensteher"). Beende mit dem Satz, der benennt, wer von ihnen es bekommen hat. Mit einem Akteur in dieser Rolle sieht eine Regel, die jemanden übergeht, genau so aus wie eine Regel, die nichts tut.

Eine aus Code abgeleitete Geschichte und nicht von einer Person ist eine Lesart dieses Codes. Sage dies neben dem Bild, damit ein Leser weiß, dass es nicht mit jemandem überprüft wurde, der die Arbeit tatsächlich ausführt. Bevor du einen geänderten Satz zeichnest, lies die Bedingung (Guard), die entscheidet, wann das neue Verhalten greift: den Zustand, den es erfordert, und das Ereignis, das es auslöst. Zeichne dieses Ereignis als den Satz vor der Änderung und füge einen Zustand, in dem sich die gesamte Geschichte befindet, wie z.B. "der abfahrende Fahrer parkt noch dort", in die Beschreibung ein. Eine Notiz wie "das nächste Mal, wenn die Warteschlange gefragt wird" nennt keinen Akteur und ist der Hinweis darauf, dass der Auslöser nie gefunden wurde.

Wie viele Geschichten

• Eine Geschichte pro wichtiger Alternative. Der Happy Path zuerst.
• AS-IS und TO-BE sind immer separate Geschichten, niemals ein Bild.
• Ein grober Überblick plus eine detaillierte Geschichte für den Schritt, der wichtig ist, wenn der Prozess umfangreich ist.
• Teile bei ungefähr fünfzehn Sätzen, unabhängig von allem anderen. Ein breites, überfülltes Bild ist die Methode, die dir sagt, dass die Geschichte zu groß ist.

Benenne einen Satz so, dass er als Satz lesbar ist: Rückerstattung - AS-IS, Rückerstattung - TO-BE.

Rendern

Schreibe eine Spezifikation als JSON und führe dann den Generator aus dem Verzeichnis aus, das diese SKILL.md enthält:

python3 scripts/story2egn.py pfad/zur/geschichte.json --preview <tmp-verzeichnis>

Nur Standardbibliothek. Es schreibt zwei Dateien neben die Spezifikation oder in --out-dir, und --preview fügt <Titel>.png in einem eigenen Verzeichnis hinzu, sodass ein Aufruf die Geschichte rendert und das Bild zur Ansicht zurückgibt. Setze --preview auf ein Scratch- oder Temp-Verzeichnis, getrennt von den Dateien, die ausgeliefert werden. Das PNG stammt von rsvg-convert, cairosvg oder inkscape, wenn eines installiert ist, andernfalls von macOS Quick Look. --help listet die anderen Formate und --date auf.

• <Titel>.egn.svg ist das Bild und das bearbeitbare Modell in einer Datei. Es öffnet sich in jedem SVG-Betrachter und kann unter https://egon.io importiert werden. Egon liest den Geschichtstitel aus dem Dateinamen, daher bestimmt der Titel in der Spezifikation den Dateinamen.
• <Titel>.board.svg ist dasselbe Bild für eine Seite. Jeder Akteur, Arbeitsgegenstand, Aktivität und Notiz befindet sich in einer Gruppe, die mit den Schritten getaggt ist, zu denen sie gehören, und trägt seinen eigenen Dunkelmodus. scripts/story-board.js kann dimmen, einkreisen oder auf einen Schritt zuschneiden. Ein von Hand auf egon.io gezeichnetes Board hat keine Tags, bleibt also ein reines Bild.

Teile dem Benutzer immer die Pfade mit, die geschrieben wurden. Zeige die Bilder inline an, wenn der Host Bilder anzeigen kann, andernfalls sind die Pfade das ausgelieferte Ergebnis. Sage niemals, dass eine Geschichte erstellt wurde, ohne ihre Datei zu nennen.

Zurücklesen einer Geschichte

.egn, .egn.svg und Legacy-.dst-Dateien werden von der zugehörigen Fertigkeit egn-to-text gelesen. Verwende sie, anstatt sie hier zu parsen.