📘 Gouvernance de la documentation – Structure & Templates¶

Projet : ProbatioVault
Statut : Normatif (obligatoire)

1. Objectif du document¶

Ce document définit :

• la structure documentaire cible du site MkDocs ProbatioVault ;
• les règles d’organisation des EPIC et User Stories ;
• les templates officiels des documents suivants :
• epic.md
• PD-XX-specification.md
• PD-XX-plan.md
• PD-XX-acceptability.md
• PD-XX-rex.md

Ce document constitue la référence unique pour toute création, modification ou refactoring de la documentation projet.

2. Principes directeurs¶

2.1 Séparation stricte des rôles¶

👉 JIRA n’est jamais la source de vérité documentaire.

2.2 Unité documentaire¶

Une User Story = un dossier = une unité de décision complète

Chaque User Story est contenue dans :

• un répertoire unique ;
• lui-même contenu dans une EPIC.

2.3 Traçabilité et auditabilité¶

La documentation doit permettre :

• une lecture du sens vers l’exécution (EPIC → US → Implémentation → REX) ;
• une relecture a posteriori sans dépendance à JIRA ;
• une exploitation par des tiers (auditeur, CPI, investisseur).

3. Structure documentaire cible¶

3.1 Arborescence globale¶

docs/
├── index.md

├── meta/
│   ├── glossary.md
│   ├── invariants-global.md
│   ├── process-workflow.md
│   └── documentation-structure.md   ← présent document

├── architecture/
│   ├── overview.md
│   ├── data-flows.md
│   ├── crypto-model.md
│   ├── worm-proof.md
│   └── legal-pre.md

├── epics/
│   ├── index.md

│   ├── <epic-name>/
│   │   ├── epic.md
│   │   ├── PD-XX-<short-name>/
│   │   │   ├── PD-XX-specification.md
│   │   │   ├── PD-XX-plan.md
│   │   │   ├── PD-XX-acceptability.md
│   │   │   └── PD-XX-rex.md
│   │   └── PD-YY-<short-name>/
│   │       └── ...
│
├── reference/
│   ├── backend-api/
│   │   └── typedoc/
│   ├── frontend-sdk/
│   │   └── typedoc/
│   └── infra/
│       └── typedoc/

├── product/
├── security-compliance/
└── changelog/

4. Règles de nommage (obligatoires)¶

• Une EPIC = un dossier en kebab-case (ex. auth-zero-knowledge)
• Une User Story = PD-XX-<short-name>
• Tous les fichiers reprennent l’ID PD
• Les 4 fichiers d’une User Story sont obligatoires, même vides au départ
• Une User Story appartient à une seule EPIC

5. Templates officiels¶

Les templates sont disponibles dans le dossier templates/ :

Utilisation : Copier le template, renommer XX avec le numéro JIRA.

6. Règle d'or finale¶

Si une information explique “pourquoi” → EPIC
Si elle explique “quoi” → Specification
Si elle explique “comment” → Implementation Plan
Si elle explique “est-ce valide” → Acceptability
Si elle explique “ce qu’on a appris” → REX

7. Statut du document¶

Ce document est normatif.
Toute déviation doit être explicitement justifiée et documentée.