# 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.
- **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.