Ustagammon/docs/adr/0008-glossaire-et-scenarios-source-unique.md

0008. Glossaire et scénarios : une source unique pour le code, l'aide et les tests

• Statut : accepté
• Date : 2026-11-02
• Décideurs : Pierre, sur proposition de Claude Code pour le format

Contexte

Le code est en anglais (ADR 0007), l'interface et la documentation en français. Il faut un lien explicite entre les deux langues pour que le code reste compréhensible et que les mots du jeu soient les mêmes partout. Le cadrage prévoit aussi un glossaire dans l'application (« chaque terme technique est touchable »).

Pierre veut une documentation utilisateur fondée sur des cas d'usage réels, orientée tâches, versionnée avec le code, consultable dans l'application, et utilisable comme base des tests de bout en bout. Il impose une seule source de vérité : aucune documentation dupliquée.

Décision

Glossaire : docs/glossaire/, un fichier par terme.

• Chaque fichier (videau.md, equite.md…) commence par un en-tête qui donne le terme français, sa traduction anglaise (le nom utilisé dans le code) et, le cas échéant, le type du domaine qui l'implémente :

  ---
  term: Videau
  english: Cube
  code: Cube
  ---
  

• Puis un titre, une ligne « En bref : » (une phrase, celle que l'app affiche quand on touche le terme), et des détails facultatifs.

• Dans le code, chaque type du domaine qui correspond à un terme porte en commentaire le chemin de sa fiche (Glossaire : docs/glossaire/videau.md).

• Des tests vérifient la forme des fiches, l'unicité des traductions anglaises, l'index, et, dès que le domaine existe, le lien dans les deux sens : chaque code: désigne un type existant, chaque référence du code désigne une fiche existante.

Documentation utilisateur : docs/scenarios/, des scénarios métier.

• Un fichier par tâche réelle de l'utilisateur (« Jouer une partie contre l'ordinateur », « Comprendre mon erreur »…), écrit pour un joueur, en français, à la deuxième personne, avec des étapes concrètes.
• Le format est du Markdown avec Gherkin (fichiers .feature.md, pris en charge par Cucumber) : le même fichier se lit comme une page d'aide et s'exécute comme test de bout en bout. Les étapes s'écrivent en français (« Étant donné », « Quand », « Alors »).
• L'outil qui exécute ces scénarios est choisi avec le socle (PWA ou Android). D'ici là, les scénarios sont déroulés à la main et servent de guide de test.

Une seule source. L'application n'a pas sa propre copie de l'aide ni du glossaire : le build les copie depuis docs/glossaire/ et docs/scenarios/ vers les ressources de l'application. Ces copies ne sont jamais commitées. La documentation affichée est donc toujours celle de la version installée.

Alternatives écartées

• Un seul fichier de glossaire : plus difficile à lier depuis le code et depuis l'application (une fiche = un lien), et des conflits de fusion fréquents.
• Documentation utilisateur rédigée à part des tests : deux textes qui divergent tôt ou tard.
• Gherkin classique (.feature) : exécutable, mais austère comme page d'aide. Le Markdown avec Gherkin donne les deux. (Choix inversé par l'amendement du 2026-11-02, ci-dessous.)
• Aide intégrée en dur dans l'application : une seconde source à maintenir.

Conséquences

• Les textes du glossaire et des scénarios sont des contenus pédagogiques, sous CC BY-SA 4.0. Leur ton relève de Pierre : les fiches rédigées par Claude Code sont marquées « à relire » jusqu'à sa relecture.
• Tout nouveau type du domaine qui correspond à un mot du jeu demande sa fiche de glossaire dans la même merge request.
• Toute fonction visible par l'utilisateur demande son scénario dans la même merge request.

Amendements

2026-11-02 — Gherkin standard, exécution sur le domaine et le moteur

Décidé par Pierre. Remplace, dans la décision ci-dessus, le format Markdown avec Gherkin et l'exécution de bout en bout par l'interface.

• Format : Gherkin standard, fichiers .feature commençant par # language: fr. Le Markdown avec Gherkin est la variante la moins outillée de Cucumber, et sa prise en charge des mots-clés français n'est pas assurée ; le Gherkin standard est compris par tous les outils. Le paragraphe libre sous Fonctionnalité: porte l'introduction destinée au joueur ; l'application met le fichier en forme comme page d'aide.
• Validation dès maintenant : make test passe chaque scénario dans l'analyseur officiel de Cucumber (@cucumber/gherkin, MIT, image docker/gherkin/), et refuse une étape égarée dans une description, signe d'un mot-clé mal orthographié que Gherkin accepterait comme texte libre.
• Exécution : piloter une application native de bout en bout serait compliqué. Les scénarios sont donc exécutés comme tests d'intégration : leurs étapes appellent directement le domaine, branché sur le vrai moteur. Ils s'écrivent en conséquence avec des intentions (« vous commencez une nouvelle partie ») et non des gestes d'interface (« vous touchez le bouton … ») : le même scénario reste vrai quelle que soit l'interface.
• Perspective : si les scénarios peuvent un jour être joués dans une instance réelle de l'application, la même exécution produira les captures d'écran de l'aide, toujours à jour avec la version installée.