Conventions documentaires

Cette page définit comment toute page de la documentation Nex doit être écrite et maintenue. Elle s’applique à tous les fichiers Markdown dans apps/docs/.

Frontmatter obligatoire

Chaque page doit commencer par un bloc YAML structuré comme suit :

---
title: "Titre lisible de la page"
audience: [dev, sec, qa, audit-bank, compliance, ops, métier]
owner: "@equipe-ou-personne"
status: stable | draft | deprecated
last_review: 2026-05-20
related_adrs: [NEX-438, NEX-500]   # optionnel
related_tickets: [NEX-790]         # optionnel
---

Champs

Champ	Obligatoire	Description
title	oui	Titre de la page tel qu’il doit apparaître. Évite de répéter le H1 ; sert au tooltip nav et au SEO.
audience	oui	Une ou plusieurs valeurs parmi : dev, sec, qa, audit-bank, compliance, ops, métier. Déclare explicitement à qui s’adresse la page.
owner	oui	Handle de l’équipe ou de la personne qui maintient la page. Format @nom-équipe ou @prenom.nom.
status	oui	stable (production-ready), draft (en construction, ne pas auditer), deprecated (conservé pour référence, ne plus suivre).
last_review	oui	Date ISO de la dernière revue. Doit être rafraîchie à chaque modification matérielle ; revue obligatoire tous les 90 jours minimum.
related_adrs	non	Liste des ADRs liés (utile pour l’onboarding et l’audit).
related_tickets	non	Liste des tickets Jira d’origine ou de suivi.

Audiences — comment choisir

• dev — un développeur qui code sur la plateforme.
• sec — un ingénieur sécurité interne ou un pentester externe.
• qa — un test engineer interne ou externe.
• audit-bank — un auditeur partenaire bancaire, BEAC, COBAC.
• compliance — un compliance officer interne ou un auditeur compliance externe.
• ops — un SRE, DevOps, ingénieur infrastructure.
• métier — une équipe non-technique (support, KAM, ops produit).

Une page peut viser plusieurs audiences. Les pages très transverses (glossaire, vue d’ensemble) en visent souvent toutes.

Statuts

Statut	Sens	Conséquence
stable	Contenu validé, à jour, audit-ready.	Affichage normal dans la nav.
draft	Contenu en construction, partiel, non auditable.	Bandeau d’avertissement en haut de page.
deprecated	Contenu obsolète, conservé pour traçabilité.	Bandeau « page dépréciée » et lien vers la page de remplacement.

Règles de rédaction

1. Langue : français pour les pages produit, métier et compliance. Anglais autorisé pour les pages techniques où le vocabulaire du framework est en anglais (NestJS, OWASP, etc.). Pas de franglais aléatoire.
2. Diacritiques : toujours respecter les accents (é, è, à, ê, ç, …). Pas de substitution ASCII.
3. Vocabulaire : utiliser les termes définis dans le glossaire. Une page qui invente un terme doit l'ajouter au glossaire ou choisir un synonyme existant.
4. Liens internes : utiliser des chemins absolus (/services/auth/overview) pour les liens entre sections. Les chemins relatifs sont tolérés à l'intérieur d'une même sous-section.
5. Diagrammes : préférer Mermaid (rendu natif VitePress) ou des images SVG/PNG dans _assets/. Bannir les diagrammes en image lourde sans alt-text.
6. Code : annoter les blocs de code avec le langage ( ```ts, ```sql, ```bash).
7. Pas de captures sans alt-text.
8. Pages overview courtes : dès qu'une page dépasse ~500 lignes, la split en pages atomiques par sujet et garder une "vue d'ensemble" courte avec un "Plan de la documentation" qui liste les sous-pages.

Callouts (containers VitePress)

Pour mettre en valeur une information dont la sévérité diffère du texte courant, utiliser les containers natifs VitePress. Ne pas se contenter d'un blockquote quand le message porte un statut critique.

Container	Quand l'utiliser
::: info	Note neutre, complément d'information, lien vers une autre page.
::: tip	Bonne pratique, raccourci utile, recommandation.
::: warning	Limite connue, pré-requis facile à oublier, attention à un piège.
::: danger	Erreur grave possible, action irréversible, dette compliance critique.
::: details	Repli sur du contenu volumineux optionnel (logs, schémas verbeux).

Syntaxe :

::: tip
Pense à rafraîchir `last_review` à chaque modification matérielle.
:::

::: warning Limite connue
Le service `logs-reporting` n'est pas encore implémenté — l'audit trail centralisé manque.
:::

::: danger Compliance
Les admin endpoints `PUT /accounts/:id/balance/*` modifient le solde **sans écriture compensatoire** → violation immutabilité ledger.
:::

::: details Voir la requête SQL complète
```sql
SELECT * FROM ledgers …
```
:::

Règle de prudence : ::: danger est réservé aux risques avérés ou aux dettes critiques. Pas de cri-au-loup.

Processus de revue

Quand rafraîchir last_review

• À chaque modification matérielle (pas une typo, mais une mise à jour de contenu).
• À chaque revue trimestrielle planifiée.
• À chaque demande d’un audit externe (la page sert d’évidence ; on date la dernière vérification).

Quand passer en deprecated

• Quand le sujet n’existe plus dans le code ou est remplacé.
• Quand la page est fusionnée dans une autre. Laisser la page existante avec un lien de redirection plutôt qu’une 404 si elle est référencée ailleurs.

Quand supprimer

• Uniquement après 6 mois minimum en statut deprecated.
• Toujours vérifier qu’aucune page ne pointe vers elle (recherche de liens internes).

Diagrammes et conventions

• C4 model : Structurizr-style ou Mermaid C4Context, C4Container, C4Component.
• Sequence diagrams : Mermaid sequenceDiagram avec annotations de trust boundaries.
• Data flow diagrams : Mermaid flowchart avec couleurs cohérentes (PII en jaune, secrets en rouge, audit en bleu).
• State machines : Mermaid stateDiagram-v2.
• ERDs : Mermaid erDiagram.

Ownership

Chaque section principale a un propriétaire désigné :

Section	Owner par défaut
/overview/	@platform-team
/architecture/	@architecture-team
/services/<service>/	équipe propriétaire du service
/flows/	@product-team + équipe ledger
/security/	@security-team
/compliance/	@compliance-team
/operations/	@platform-ops
/qa/	@qa-team
/dev/	@platform-team
/usage/	@support-ops
/governance/	@platform-team

Le champ owner du frontmatter permet de surcharger ce défaut par page.