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 :

• aux Capabilities
• aux APIs
• aux Domain Events
• aux Tests QA
• aux User Stories
• aux Prompts IA

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

PDF

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

PDF

Recherche

Index

Produire automatiquement :

Documentation HTML

PDF

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 :

• développeurs
• testeurs
• Product Owner
• commerciaux
• support
• intégrateurs
• consultants
• partenaires
• clients Enterprise
• IA

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/

• Public.
• Lecture.
• Recherche.
• PDF.
• Diagrammes.
• Navigation.
• API.

• –> Aucune édition.

• Privé.
• Authentification.
• Edition.
• Publication.
• Validation.
• Gestion Git.
• Assistant IA.

• Anonymous
• Developer
• Partner
• Customer
• Employee

• DOC_WRITER
• DOC_REVIEWER
• DOC_OWNER
• SUPER_ADMIN

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 :

• 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.).

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.