Aller au contenu

ADR-006 — Doc métier co-localisée in-app
Statut Accepted
Date 07/05/2026 (S19 mid-week)
Décideurs Romain BAZIL, Nicolas Léonard
Origine Synchro S19 mid-week §6

Contexte

L'archi de l'outil d'analyse devient dense. Romain : « je me souviens plus de ce que j'ai implémenté il y a 2 mois. » Si lui-même se perd dans son propre code, les AM, analystes et nouveaux contributeurs n'ont aucune chance.

Cas concret S19 : un "45 m²" préfilled dans la colonne Actuel, sans validation AM ni source visible. Personne ne sait expliquer pourquoi. Le workflow de pré-remplissage existe mais n'est documenté nulle part.

Trois options testées historiquement :

  1. Pas de doc → personne ne comprend, drift permanent
  2. Doc en .md séparé du code (ex. Notion, Confluence) → dérive du code, lue 1× et oubliée
  3. Doc co-localisée in-app (popover sur la section concernée) → présentée au moment où la question se pose

Décision

Pour les règles de précédence, les workflows de calcul, et les modes de fonctionnement métier de l'outil d'analyse : doc co-localisée in-app, en popover sur chaque section concernée.

Mécanisme cible

  • Sur chaque section / panneau de l'outil d'analyse : un bouton/icône "ℹ️" (ou hover tooltip) en haut à droite
  • Au clic : panneau latéral ou popover qui explique :
  • Quelles sont les sources consommées
  • Quelles sont les règles de précédence appliquées
  • Comment interpréter les conflits / la valeur retenue
  • Le mode de calcul si applicable

Format de la doc

Markdown stocké dans le repo (project-analysis) co-localisé avec le composant ou centralisé dans un dossier docs/in-app/ à arbitrer. À cadrer avec Nicolas en S20.

Pour les contributeurs tech

Les conventions de code, les ADR et la doctrine restent dans ce wiki + dans CLAUDE.md. La doc in-app est uniquement la doc consommée dans l'usage (par AM, analyste, Romain qui revient sur son code).

Rationale

Pourquoi la co-localisation

  • Capture passive d'utilité : l'AM consulte la doc quand il a la question, pas quand on lui demande
  • Pas de drift : la doc vit dans le repo, donc si le code change sans toucher la doc, c'est visible (revue PR)
  • Onboarding implicite : un nouvel AM apprend en utilisant l'outil

Pourquoi pas Notion

  • Lue 1× et oubliée
  • Pas de versioning lié au code
  • Drift garanti à 6 mois

Pourquoi pas un README dans le repo

  • Personne ne va le chercher quand il a un doute sur une UI
  • Bon pour les contributeurs tech, pas pour les utilisateurs métier

Conséquences

Ce qui change

  1. Chaque section critique de l'outil d'analyse doit avoir un point de doc accessible in-app
  2. Convention à définir : où vivent les .md (co-localisé component vs centralisé docs/in-app/)
  3. Les premiers cas à documenter (priorité S20) :
  4. Règles de pré-fill de la colonne Actuel
  5. Hiérarchie de précédence par champ (ADR-003)
  6. Mode de calcul estimate_value (méthodes + pondération)
  7. Wording du bandeau "champs critiques manquants" + comment ça se calcule

Ce qu'il faut faire

  • Convention technique : MDX in-app ? Markdown rendered en popover ? À cadrer en S20
  • Pilote sur fiche consolidée (déjà chantier en cours, contexte naturel)
  • Backport sur les autres sections critiques au fil de l'eau

Ce qu'il faut éviter

  • Tout documenter : on ne documente que ce qui est non évident à partir de l'UI
  • Doc qui répète le code : c'est de la doc métier, pas de la doc d'API
  • Ouvrir un Notion en parallèle : on ré-ouvre la porte au drift

Alternatives écartées

  • Doc Notion : drift garanti, pas de versioning lié au code
  • README repo : pour les contributeurs tech, pas pour les utilisateurs in-context
  • Pas de doc : c'est l'option actuelle, et le cas du "45 m² préfilled sans source" en montre les limites
  • Bricks Docs system (Docusaurus) : projet en backlog côté Bricks Engineering, pas dispo à court terme. Quand il existera, il pourra cohabiter avec la doc in-app (Docusaurus = doc tech globale, in-app = doc métier ciblée)

Verbatims

« Je pense qu'il faudrait qu'on commence à documenter un petit peu in-app la façon dont ça fonctionne. Tu pourrais avoir en haut à droite de chaque section un contexte métier, quelles sont les règles, comment ça fonctionne. Je commence à être vraiment dense comme projet, et là, je me souviens plus de ce que j'ai implémenté il y a deux mois. » — Romain

« Ce qui est pas mal quand ça vit dans le produit, c'est que c'est au moment que tu te poses la question que tu as la réponse. » — Romain

« Pouvoir survoler et comprendre comment est-ce que le truc, il fonctionne. Est-ce qu'ils vont le lire dans le détail ? Peut-être pas, mais ça aurait été cool de repasser dessus et de dire : ok, c'est ça le mode de fonctionnement. Plus proche du produit, mieux dans le besoin. » — Nicolas

Voir aussi

Sources