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
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 :
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.
Documentation Platform ├── Documentation Repository ├── Documentation Generator ├── Publication Engine ├── Search Engine ├── Documentation API ├── Documentation AI Agent ├── Documentation Validator ├── Documentation Preview └── Documentation Portal
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/
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é.
Tous les documents commencent par :
id: title: version: status: playbook: capability: workspace: roles: owner: created: updated: related: tags:
Operating Model
Playbook
Capability
Procedure
Architecture
Decision Record
API
Prompt
Test
Diagram
Template
Release Note
Roadmap
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
Le générateur produit automatiquement :
Navigation
Index
Sommaires
Liens croisés
Graphes
Diagrammes
Recherche
Glossaire
Documentation HTML
Site documentaire
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
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
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
Recherche globale :
Playbooks
Capabilities
Procédures
API
Events
Prompts
Tests
Glossaire
Recherche plein texte.
Construire automatiquement le graphe documentaire.
Exemple :
Sales Playbook ↓ CAP-SALES-PROSPECT ↓ SALES-001 ↓ POST /prospects ↓ LeadCreated ↓ QA-SALES-001-001 ↓ PROMPT-SALES-001
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.
Créer un dépôt :
documentation
Branches :
main
develop
feature/*
Toutes les modifications passent par Pull Request.
Déclencheurs :
Push
Pull Request
Release
Actions :
Validation
Génération
Publication
Recherche
Index
Produire automatiquement :
Documentation HTML
Version imprimable
Archive ZIP
Utiliser :
MkDocs Material
Pourquoi :
Navigation exceptionnelle
Recherche rapide
Mermaid
PlantUML
OpenAPI
Versioning
Dark Mode
Responsive
Très utilisé
Documentation as Code
Créer un Workspace spécifique.
Menus :
Dashboard
Playbooks
Capabilities
Procedures
Architecture
API
Tests
Prompts
Diagrams
Assets
Templates
Search
Publications
Settings
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
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.
Versionnement Git obligatoire.
Historique complet.
Validation avant publication.
Aucune édition directe du site publié.
✓ Documentation Repository
✓ Documentation Portal
✓ Documentation API
✓ Documentation Validator
✓ Documentation Generator
✓ Documentation Search
✓ Documentation Graph
✓ GitHub Actions
✓ MkDocs
✓ Agent IA
✓ Publication automatique
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é.
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 :
Elles méritent donc leur propre implantation.
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.
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 Repository ↓ Documentation Generator ↓ MkDocs ↓ Documentation Portal et Documentation Console ↓ Git ↓ Repository ↓ Generator ↓ Publication
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 :
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.).
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.