Gestion de la documentation

Fonctionnel

La documentation doit permettre à un développeur humain ou IA de comprendre :

• ce qui existe ;
• ce qui est cible ;
• ce qui est réellement implémenté ;
• ce qui est seulement préparé ;
• les décisions fonctionnelles ;
• les décisions techniques.

Structure documentaire retenue

doc.html
doc/
  01-...
  02-...
  ...
docs/
  architecture/
  adr/
  implementation-status/

Rôle de doc.html

doc.html est le portail documentaire racine.

Il doit :

• lister toutes les entrées Markdown ;
• permettre une recherche globale ;
• pointer vers les fichiers .md ;
• rester lisible hors application.

Rôle du dossier /doc

/doc contient la documentation métier et architecture découpée par sujet.

Chaque fichier doit idéalement contenir :

• une partie fonctionnelle ;
• une partie technique ;
• les décisions validées ;
• les points non encore implémentés si nécessaire.

Rôle du dossier /docs

/docs est le dossier projet standard du monorepo.

Il peut contenir :

• architecture ;
• ADR ;
• contrats techniques ;
• schémas ;
• état d’implémentation ;
• runbooks ;
• exploitation.

Règle importante

Quand une décision structurante est prise, elle doit être ajoutée dans la documentation.

Exemples :

• séparation dev/viewer ;
• Docker ;
• Workspace Views ;
• Widget Collections ;
• dependency graph ;
• publication Draft/Published ;
• dashboard multi-datasets.

Documentation et IA

Pour qu'une IA puisse reprendre le projet correctement, les documents doivent être explicites sur :

• les noms des concepts ;
• les responsabilités des modules ;
• les fichiers de référence ;
• les zones non encore fonctionnelles ;
• les décisions figées.