Convention de documentation Quantis

Cette page est la convention : une codification de documentation partagée par tous les modules Quantis, pour une navigation homogène d'un module à l'autre et une exploitation à l'échelle de la plateforme. ActuaryLab en est l'implémentation de référence (modèle doc-as-service) ; les modules suivants la copient.

Les quatre piliers

1. Taxonomie — Diátaxis

Toute doc se range dans quatre catégories (jamais d'autres) :

Catégorie	Question	Dossier
Tutoriels	« Comment j'apprends en faisant ? »	docs/tutorials/
Guides pratiques	« Comment je résous cette tâche ? »	docs/how-to/
Référence	« Quel est le détail factuel ? »	docs/specs/, docs/reference/
Explication	« Pourquoi c'est ainsi ? »	docs/explanation/, docs/plan/, docs/formalisation/

Plus une rubrique À propos (docs/about/) pour la méta (cette page, provenance).

2. Outil — MkDocs Material + charte BFEV

• mkdocs.yml à la racine du dépôt, thème Material, langue fr.
• Charte commune : docs/assets/extra.css (palette vert #237227 / ambre #ffaa00), Roboto. La palette est identique pour tous les modules — seuls site_name et logo changent (unité visuelle Quantis).
• arithmatex + MathJax pour les formules (utile aux modules à contenu mathématique).

3. Déploiement — doc-as-service

La doc est un service du stack Compose du module (docs/Dockerfile → nginx), géré au même titre que backend / frontend, pas un déploiement séparé.

Leçon de bfev (module 1)

Le module bfev déploie sa doc séparément — considéré rétrospectivement comme une erreur. ActuaryLab corrige le tir : doc = service du module. À répliquer partout, et à rétrofiter sur bfev.

Domaine : docs.<module>.nedcore.net (ici docs.quantis-actuarylab.nedcore.net), aux côtés de app. et api..

⚠️ Doc interne : accès en phase QA

La doc est interne (pas un livrable client). Pendant le QA, elle est servie en accès public (nginx simple) : le coût d'un verrou (basic auth) s'est révélé plus élevé que le risque en phase privée — UX du dialogue natif moche, pas de révocation par personne, et un fail-closed qui mettait le service à terre. Le lien « Documentation » du rail n'apparaît qu'au staff interne (junior + senior) : consultant client ET actuaire externe en sont exclus. Cible (post-QA) : doc derrière le SSO Quantis/YODICORE (login brandé, révocation centralisée) — voir BACKLOG.md C-2. Bloquant aujourd'hui : les personas de test (junior/externe/client) ne sont pas encore dans YODICORE (accès direct).

4. Cycle de vie

La doc suit le versionnage du code : même dépôt, même cycle de release. Travail terminé → maj docs/ → commit + push → Dokploy redéploie → page à jour. Multi-versions via mike si/quand le besoin apparaît.

Adopter la convention dans un nouveau module

1. Copier mkdocs.yml, docs/assets/, docs/Dockerfile, docs/nginx.conf, requirements-docs.txt ; ajuster site_name et le logo.
2. Ajouter le service docs au docker-compose.yml du module.
3. Ranger le contenu dans les quatre dossiers Diátaxis.
4. Ajouter le domaine docs.<module>.nedcore.net dans Dokploy.

Call-outs (encadrés) — vocabulaire partagé

Pour alléger la charge cognitive, les éléments qui doivent ressortir (à retenir, pièges, dangers) sont mis en call-outs (admonitions Material). Vocabulaire fermé et commun à tous les modules — un lecteur apprend une fois « encadré ambre = à retenir, encadré rouge = piège ».

Call-out	Type Material	Quand l'utiliser
🎯 À retenir	abstract	Les 2-3 points clés, en tête d'une page dense (TL;DR).
⚠️ Piège	warning	Erreur facile à commettre / contre-intuitif (ex. uv run au lieu du venv backend).
🛑 Irréversible	danger	Action destructrice ou qui casse la prod (ex. colonne hors _COLONNES_AJOUTEES → 500).
💡 Astuce	tip	Raccourci utile, non essentiel.
🔒 Oracle scellé	note	Source de vérité unique à ne pas réimplémenter (cas-témoins, oracles).
🧪 Exemple	example	Cas concret rejouable.
Info	info	Contexte, audience, périmètre (sans emoji : neutre).

🎯 À retenir

C'est l'encadré de tête : objet de la page + les points qui comptent. Accent ambre BFEV pour le repérer d'un coup d'œil.

⚠️ Piège

Le runner de validation tourne sous backend/.venv/bin/python, pas uv run (l'env racine n'a pas sqlmodel).

🛑 Irréversible

Toute colonne ajoutée à un modèle doit figurer dans _COLONNES_AJOUTEES (db.py), sinon 500 en prod (SQLite déployée).

Règle de parcimonie. 2 à 4 call-outs par page au maximum : un encadré tous les trois paragraphes n'attire plus l'œil, il le sature. Pour replier un long détail annexe, préférer le call-out dépliable (??? au lieu de !!!).

Qualité du build

• Build en mkdocs build --strict (cf. docs/Dockerfile) : un lien interne cassé fait échouer le build. Les ancres des specs importées depuis Word (style GitHub, #…-périmètre) résolvent grâce au slugify aligné (toc.slugify = pymdownx.slugs.slugify(case=lower), mkdocs.yml), et validation.links.anchors: warn rend ces ancres bloquantes sous --strict. En écrivant une nouvelle page, viser des ancres conformes à ce slugify (minuscules, accents préservés, ponctuation supprimée).

Dette connue (à durcir)

• Mutualisation : la machinerie est aujourd'hui copiée par module. Quand un 3ᵉ module arrive, extraire un outil partagé quantis-docs (le coût DRY justifiera alors le refactor — durcissement juste-à-temps).