johanhaleby/domain-storytelling

Domain Storytelling

Une histoire de domaine est une image d'un processus métier raconté sous forme de phrases : un acteur fait quelque chose avec un objet de travail, impliquant parfois un autre acteur. Les numéros sur les flèches indiquent l'ordre. Rien d'autre ne le fait.

Ce skill modélise l'histoire, puis la génère. Lisez references/notation.md et references/spec.md en un seul appel avant de modéliser quoi que ce soit de non trivial. Le fichier de spécification répertorie chaque nom d'icône.

Étapes

1. Modélisez l'histoire. Le brouillon est par défaut : modélisez le cas typique d'après ce que l'utilisateur a décrit, choisissez des icônes, générez, et dites quelles hypothèses vous avez faites. Ne demandez que lorsqu'un choix modifierait le modèle plutôt que de le décorer.
2. Relisez les phrases une fois et demandez lesquelles sont facultatives, ou se produisent parfois différemment. Celles-ci deviennent des annotations. C'est l'étape la plus facile à sauter, et la sauter coûte le plus cher, car la notation n'a pas de branche. Une étape qui n'arrive que parfois porte soit une annotation, soit rejoint silencieusement le chemin heureux.
3. Animez un atelier à la place lorsque l'utilisateur en fait la demande (/domain-storytelling workshop, « anime un atelier », « interviewe-moi à ce sujet ») ou lorsqu'un plan repose sur un processus que personne n'a formalisé. Lisez references/workshop.md maintenant. N'interviewez jamais et ne dessinez pas en même temps.
4. Écrivez la spécification et générez-la comme indiqué dans la section Rendu ci-dessous.
5. Agissez sur les avertissements. Lorsque le générateur écrit quoi que ce soit sur stderr, lisez references/warnings.md maintenant. Le générateur se termine par une ligne nommant ce fichier, donc une lecture ignorée apparaît dans la sortie.
6. Inspectez l'image en lisant le PNG d'aperçu écrit par le rendu, et nommez chaque fichier écrit. Un rendu est terminé lorsqu'il n'a pas d'avertissements et que l'image se trace proprement.

Règles non négociables

Elles proviennent de la méthode, et les enfreindre produit quelque chose qui ressemble à une histoire de domaine mais n'en est pas une.

• Chaque acteur apparaît exactement une fois. Une forme par acteur, quel que soit le nombre de phrases dans lesquelles il apparaît.
• Deux personnes jouant des rôles différents sont deux acteurs, même si le domaine les appelle pareil. La règle ci-dessus concerne un acteur dessiné une fois, pas un mot dessiné une fois. Avant de fusionner deux mentions du même nom, demandez-vous si une seule personne pourrait effectuer les deux étapes. Lorsque ce n'est pas le cas, ce sont des acteurs séparés, et ils obtiennent des formes et des noms séparés qui précisent quel rôle chacun joue ici. Les numéros de séquence sont ce qui rend cela erroné plutôt que simplement vague, car ils affirment que l'acteur effectuant la phrase 5 est celui qui a effectué la phrase 2. Un conducteur unique qui rejoint la file d'attente d'un classement, libère une place de stationnement, puis réclame la place libérée suggère qu'un conducteur a abandonné une place de stationnement et se l'est vue réoffrir, alors que le détenteur partant et le fileur sont deux rôles partageant un même intitulé de poste. Une annotation nommant quelqu'un d'autre qui pourrait effectuer l'étape, « un administrateur peut libérer la place de stationnement à la place », est l'indice que l'acteur de l'étape n'a jamais été déterminé.
• Chaque activité dessine son propre objet de travail. La même commande dans trois phrases donne trois formes. Ce n'est pas une duplication, c'est ainsi que la notation montre le déplacement de la chose.
• Pas de conditionnelles, de branches ou de boucles. Il n'y a pas de passerelle, pas de losange, pas de « si » en pointillé. Modélisez une alternative importante sous forme d'histoire séparée. Conservez une petite variation sous forme d'annotation.
• Une phrase commence par un acteur et le numéro de séquence se trouve sur cette première flèche. La flèche vers un deuxième acteur porte une préposition, pas un numéro.
• Les phrases qui se produisent en même temps partagent un même numéro, et n'importe combien d'entre elles peuvent le faire. Répétez la valeur n entre elles dans la spécification. C'est la seule façon pour la notation de dire « en même temps », car elle n'a ni bifurcation ni jonction, donc utilisez-la chaque fois qu'aucune étape n'attend l'autre. Gardez les numéros séparés lorsqu'une étape suit véritablement l'autre, car un numéro partagé affirme plus que « ces deux étapes sont liées ».
• Utilisez les propres mots du domaine. Le verbe sur la flèche est le mot que l'expert du domaine a prononcé. Si vous vous surprenez à écrire « traite » ou « gère », c'est que vous n'avez pas encore compris l'étape, alors demandez. Dans une histoire tirée du code, le mot du domaine est le nom de l'action qu'une personne déclenche, le bouton, le point de terminaison ou la commande, donc un point de terminaison cancel-reservation fait « annule la réservation ». Chaque verbe nomme une action, et deux actions différentes dans une même histoire reçoivent deux verbes différents. Suivez le point de terminaison jusqu'à l'écran qui l'appelle avant de nommer l'acteur, et nommez l'acteur d'après les utilisateurs de cet écran, car un utilisateur du back-office et un service expert dans l'éditeur administratif sont des rôles différents qui peuvent faire des choses différentes. Lorsqu'une action voisine a un effet similaire, annuler la réservation d'une place de stationnement par rapport à supprimer le fileur de la file d'attente, la note nomme l'écran et le bouton, et le voisin qu'il n'est pas.
• Un objet de travail est un nom que le domaine utilise déjà. « Facture », « Réclamation de place de stationnement ». Un et dans le nom est l'indice qu'il y en a deux, et la correction consiste à choisir celui que l'activité déplace vraiment ou à écrire deux phrases partageant un numéro. La longueur est le symptôme plutôt que la faute, donc raccourcir un nom composé pour l'adapter ne fait que le cacher.
• Dites le périmètre à voix haute. Granularité, instant dans le temps, pureté du domaine. Une histoire sans eux est ambiguë quant à ce qu'elle prétend même. Cela se trouve dans la spécification et dans la description Egon plutôt que sur l'image, car ces trois termes sont la méthode qui s'adresse au modélisateur et un lecteur de l'image ne peut pas les décoder.

Montrer où un changement atterrit

Lorsque le but de l'histoire est ce qu'un changement fait à un processus, marquez les phrases qu'il touche avec "changed": true et dites-le dans la description. Une image avec le delta marqué l'emporte généralement sur deux images que le lecteur doit comparer visuellement. Dessinez plutôt une histoire AS-IS et une histoire TO-BE lorsque la forme du processus a changé, c'est-à-dire que des étapes ont été déplacées entre acteurs ou ont disparu, plutôt que lorsque les étapes sont restées en place et que seul leur contenu a changé.

Lorsque le changement décide qui reçoit quelque chose, une offre, une priorité ou un tour, dessinez le contraste : la personne qui perd et celle qui gagne, sous forme de deux acteurs dans le même rôle nommés par leur position (« Premier fileur », « Deuxième fileur »). Terminez par la phrase qui nomme lequel d'entre eux l'a obtenu. Avec un seul acteur dans ce rôle, une règle qui ignore quelqu'un ressemble exactement à une règle qui ne fait rien.

Une histoire tirée du code plutôt que d'une personne est une lecture de ce code. Dites-le à côté de l'image, afin qu'un lecteur sache qu'elle n'a pas été vérifiée auprès de quiconque effectue le travail. Avant de dessiner une phrase modifiée, lisez la garde qui décide quand le nouveau comportement s'applique : l'état qu'il nécessite et l'événement qui l'exécute. Dessinez cet événement comme la phrase avant le changement, et mettez un état que l'histoire entière conserve, comme « le conducteur partant est toujours garé là », dans la description. Une note comme « la prochaine fois que la file d'attente est interrogée » ne nomme aucun acteur, et est l'indice que le déclencheur n'a jamais été trouvé.

Combien d'histoires

• Une histoire par alternative importante. Le chemin heureux en premier.
• AS-IS et TO-BE sont toujours des histoires séparées, jamais une seule image.
• Un aperçu grossier plus une histoire détaillée pour l'étape qui compte, lorsque le processus est vaste.
• Séparez à environ quinze phrases quoi qu'il en soit. Une image large et chargée est la méthode qui vous dit que l'histoire est trop grande.

Nommez un ensemble pour qu'il se lise comme un ensemble : Remboursement - AS-IS, Remboursement - TO-BE.

Rendu

Écrivez une spécification au format JSON, puis exécutez le générateur depuis le répertoire contenant ce SKILL.md :

python3 scripts/story2egn.py chemin/vers/histoire.json --preview <répertoire temporaire>

Bibliothèque standard uniquement. Il écrit deux fichiers à côté de la spécification, ou dans --out-dir, et --preview ajoute <Titre>.png dans un répertoire qui lui est propre, donc un appel rend l'histoire et renvoie l'image à lire. Pointez --preview vers un répertoire temporaire ou de travail, à l'écart des fichiers qui sont livrés. Le PNG provient de rsvg-convert, cairosvg ou inkscape lorsque l'un d'eux est installé, et de macOS Quick Look sinon. --help liste les autres formats et --date.

• <Titre>.egn.svg est l'image et le modèle modifiable dans un seul fichier. Il s'ouvre dans n'importe quel visualiseur SVG et s'importe sur https://egon.io. Egon lit le titre de l'histoire à partir du nom de fichier, donc le titre dans la spécification détermine le nom du fichier.
• <Titre>.board.svg est la même image pour une page. Chaque acteur, objet de travail, activité et note se trouve dans un groupe étiqueté avec les étapes auxquelles il appartient, et il porte son propre mode sombre. scripts/story-board.js peut atténuer, entourer ou recadrer sur une seule étape. Un tableau dessiné à la main sur egon.io n'a pas d'étiquettes, donc il reste une image simple.

Dites toujours à l'utilisateur les chemins qui ont été écrits. Montrez les images en ligne si l'hôte peut afficher des images, sinon les chemins sont la livraison. Ne dites jamais qu'une histoire a été produite sans nommer son fichier.

Lire une histoire

Les fichiers .egn, .egn.svg et .dst (format hérité) sont lus par le skill frère egn-to-text. Utilisez-le plutôt que de les analyser ici.