====== Sprint DOC-01 ====== Documentation Platform Objectif : Créer une plateforme de gestion documentaire "Documentation as Code" permettant de produire, maintenir, versionner, publier et générer automatiquement l'ensemble de la documentation de la plateforme SaaS. Statut : Nouveau Priorité : Très haute Complexité : Très élevée Durée estimée : 2 à 4 semaines ---- ===== Vision ===== La documentation devient un produit à part entière. Les documents ne sont plus édités directement dans un Wiki. La source de vérité est un dépôt Git. Les sites documentaires sont générés automatiquement. Les agents IA participent à la rédaction. Les Playbooks deviennent la référence métier. Toutes les procédures sont reliées : * aux Capabilities * aux APIs * aux Domain Events * aux Tests QA * aux User Stories * aux Prompts IA ---- ===== Objectifs ===== Créer un référentiel documentaire unique. Supprimer le copier/coller. Versionner toute la documentation. Publier automatiquement la documentation. Permettre aux IA de créer les documents. Garantir la cohérence documentaire. Créer une traçabilité complète. ---- ===== Architecture cible ===== Documentation Platform ├── Documentation Repository ├── Documentation Generator ├── Publication Engine ├── Search Engine ├── Documentation API ├── Documentation AI Agent ├── Documentation Validator ├── Documentation Preview └── Documentation Portal ---- ===== Arborescence Git ===== documentation/ operating-model/ playbooks/ sales/ platform/ billing/ support/ marketing/ owner/ guest/ reservation/ property/ ai/ security/ compliance/ capabilities/ sales/ platform/ billing/ support/ ... procedures/ SALES/ BILL/ PLAT/ SUP/ ... user-stories/ api/ events/ prompts/ qa/ diagrams/ assets/ templates/ ---- ===== Format documentaire ===== Tous les documents utilisent : Markdown Front Matter YAML Mermaid PlantUML OpenAPI JSON Schema Aucun document n'est stocké dans une base SQL. Git devient la source de vérité. ---- ===== Front Matter ===== Tous les documents commencent par : id: title: version: status: playbook: capability: workspace: roles: owner: created: updated: related: tags: ---- ===== Types de documents ===== Operating Model Playbook Capability Procedure Architecture Decision Record API Prompt Test Diagram Template Release Note Roadmap ---- ===== Structure documentaire ===== Niveau 0 Operating Model ↓ Niveau 1 Playbooks ↓ Niveau 2 Capabilities ↓ Niveau 3 Procedures ↓ Niveau 4 User Stories ↓ Niveau 5 API ↓ Niveau 6 Events ↓ Niveau 7 Tests ↓ Niveau 8 Prompts IA ---- ===== Générateur ===== Le générateur produit automatiquement : Navigation Index Sommaires Liens croisés Graphes Diagrammes Recherche Glossaire PDF Documentation HTML Site documentaire ---- ===== Documentation Portal ===== Créer une nouvelle application : Documentation Portal Fonctions : Explorer Rechercher Prévisualiser Comparer les versions Visualiser les graphes Télécharger PDF Voir les diagrammes Voir les dépendances ---- ===== Documentation API ===== Créer une API interne. Exemples : GET /documentation/playbooks GET /documentation/procedures GET /documentation/capabilities GET /documentation/search GET /documentation/graph GET /documentation/tree POST /documentation/generate POST /documentation/validate ---- ===== Documentation Validator ===== Le validateur contrôle automatiquement : unicité des IDs références cassées Playbooks inexistants Capabilities inexistantes API non référencées liens morts diagrammes invalides Mermaid OpenAPI Front Matter structure documentaire numérotation ---- ===== Documentation Search ===== Recherche globale : Playbooks Capabilities Procédures API Events Prompts Tests Glossaire Recherche plein texte. ---- ===== Documentation Graph ===== Construire automatiquement le graphe documentaire. Exemple : Sales Playbook ↓ CAP-SALES-PROSPECT ↓ SALES-001 ↓ POST /prospects ↓ LeadCreated ↓ QA-SALES-001-001 ↓ PROMPT-SALES-001 ---- ===== Documentation AI ===== Créer un agent spécialisé. Fonctions : Créer un document. Modifier un document. Créer une procédure. Créer un Playbook. Créer une Capability. Créer les tests. Créer les prompts. Créer les diagrammes. Vérifier la cohérence. Préparer une Pull Request. ---- ===== GitHub ===== Créer un dépôt : documentation Branches : main develop feature/* Toutes les modifications passent par Pull Request. ---- ===== GitHub Actions ===== Déclencheurs : Push Pull Request Release Actions : Validation Génération Publication PDF Recherche Index ---- ===== Publication ===== Produire automatiquement : Documentation HTML PDF Version imprimable Archive ZIP ---- ===== Moteur documentaire ===== Utiliser : MkDocs Material Pourquoi : Navigation exceptionnelle Recherche rapide Mermaid PlantUML OpenAPI Versioning Dark Mode Responsive Très utilisé Documentation as Code ---- ===== Documentation Workspace ===== Créer un Workspace spécifique. Menus : Dashboard Playbooks Capabilities Procedures Architecture API Tests Prompts Diagrams Assets Templates Search Publications Settings ---- ===== Dashboard ===== Afficher : Nombre de Playbooks Nombre de Capabilities Nombre de Procédures Couverture QA Couverture API Couverture IA Liens cassés Dernières modifications Activité Git ---- ===== Convention documentaire ===== Une Capability appartient toujours à un Playbook. Une Procédure appartient toujours à une Capability. Une User Story référence une Procédure. Une API référence une Procédure. Un Event référence une Procédure. Un Test référence une Procédure. Un Prompt référence une Procédure. ---- ===== Sécurité ===== Versionnement Git obligatoire. Historique complet. Validation avant publication. Aucune édition directe du site publié. ---- ===== Livrables ===== ✓ Documentation Repository ✓ Documentation Portal ✓ Documentation API ✓ Documentation Validator ✓ Documentation Generator ✓ Documentation Search ✓ Documentation Graph ✓ GitHub Actions ✓ MkDocs ✓ Agent IA ✓ Publication automatique ---- ===== Définition de terminé ===== La Documentation Platform est considérée terminée lorsque : ✓ la documentation est entièrement versionnée dans Git ✓ tous les documents possèdent un Front Matter normalisé ✓ les Playbooks sont publiés automatiquement ✓ les Capabilities sont reliées aux Playbooks ✓ les Procédures sont reliées aux Capabilities ✓ les APIs sont reliées aux Procédures ✓ les Domain Events sont reliés aux Procédures ✓ les Tests sont reliés aux Procédures ✓ les Prompts IA sont reliés aux Procédures ✓ les liens sont validés automatiquement ✓ un site MkDocs est généré automatiquement ✓ une recherche plein texte est disponible ✓ un graphe documentaire est généré ✓ un agent IA est capable de créer et maintenir automatiquement la documentation ✓ aucune documentation n'est modifiée directement sur le site publié. ---- ===== Recommandation d'implantation pour les applications ===== Ma recommandation : 2 applications distinctes Elle ne sont intégrées ni à la Platform Console ni au Tenant Console. Cela se traduit par deux nouvelles interfaces. Platform Marketing Website Platform Console Tenant Console Owner Portal Guest Portal Experience Builder Documentation Portal ← nouveau pour la consultation Documentation Console ← nouveau pour la gestion Pourquoi ? Parce que la documentation concerne beaucoup plus de personnes que les administrateurs de la plateforme. Elles seront utilisées par : * développeurs * testeurs * Product Owner * commerciaux * support * intégrateurs * consultants * partenaires * clients Enterprise * IA Elles méritent donc leur propre implantation. ==== Définition des modes ==== === Mode Consultation === Accessible à beaucoup de monde. Exemple : https://docs.rental-platform.com Menus : Accueil Recherche Playbooks Capabilities Procédures API Architecture Glossaire Diagrammes Release Notes Très proche de la documentation de Stripe. === Mode Auteur === Accessible uniquement aux équipes internes. Documentation Console Là, on retrouve une interface d'administration. Menus : Dashboard Playbooks Capabilities Procedures Templates Prompts Publications Git Validation AI Assistant Settings Ce n'est plus un wiki. C'est un CMS documentaire. apps/ documentation-portal/ documentation-console/ === Documentation Portal === * Public. * Lecture. * Recherche. * PDF. * Diagrammes. * Navigation. * API. * --> Aucune édition. === Documentation Console === * Privé. * Authentification. * Edition. * Publication. * Validation. * Gestion Git. * Assistant IA. ==== Les droits ==== === Documentation Portal === * Anonymous * Developer * Partner * Customer * Employee === Documentation Console === * DOC_WRITER * DOC_REVIEWER * DOC_OWNER * SUPER_ADMIN ==== L'architecture ==== Documentation Repository ↓ Documentation Generator ↓ MkDocs ↓ Documentation Portal et Documentation Console ↓ Git ↓ Repository ↓ Generator ↓ Publication ==== L'IA ==== C'est ici que ça devient intéressant. Le Documentation Console pourrait avoir un Workspace : AI Documentation avec : Créer un Playbook Créer une Capability Créer une Procédure Créer des Tests Créer une API Créer un Diagramme Créer les Prompts Vérifier la cohérence Préparer une Pull Request En réalité, le développeur ne rédige presque plus. Il valide. Et pour aller encore plus loin; on peut créer un Documentation Engine, exactement comme on a maintenant un : Notification Engine Workflow Engine Search Engine Theme Engine Le Documentation Engine serait un package partagé : packages/ documentation-engine/ Il fournirait : * génération des menus ; * recherche ; * rendu Markdown ; * Mermaid ; * PlantUML ; * Front Matter ; * validation ; * graphes ; * indexation ; * publication. Ainsi, Documentation Portal et Documentation Console utiliseraient le même moteur, comme Platform Console et Tenant Console partagent déjà des moteurs (UX Platform, Search, Notifications, etc.). ==== Au final ==== Ce n'est pas une interface isolée supplémentaire, mais un nouveau domaine fonctionnel de la plateforme : Documentation Platform │ ├── Documentation Engine (package partagé) ├── Documentation Console (back-office) └── Documentation Portal (consultation) C'est cohérent avec l'architecture que nous avons construite jusqu'ici : chaque grand domaine (CRM, Billing, UX, Identity, Documentation...) possède son moteur partagé et une ou plusieurs interfaces spécialisées. À mon sens, cette organisation sera beaucoup plus pérenne qu'une intégration de la documentation dans la Platform Console.