Crealcs Development DokuWiki

Vous affichez une ancienne révision du document ! Si vous l'enregistrez, vous créerez une nouvelle version avec ce contenu.

====== 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 =====

<code>

Documentation Platform

├── Documentation Repository
├── Documentation Generator
├── Publication Engine
├── Search Engine
├── Documentation API
├── Documentation AI Agent
├── Documentation Validator
├── Documentation Preview
└── Documentation Portal

</code>

----

===== Arborescence Git =====

<code>

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/

</code>

----

===== 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:

</code>

----

===== 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 :

<code>

Sales Playbook

↓

CAP-SALES-PROSPECT

↓

SALES-001

↓

POST /prospects

↓

LeadCreated

↓

QA-SALES-001-001

↓

PROMPT-SALES-001

</code>

----

===== 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.

<code>
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
</code>

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 :

<code>
https://docs.rental-platform.com
</code>

Menus :

<code>
Accueil

Recherche

Playbooks

Capabilities

Procédures

API

Architecture

Glossaire

Diagrammes

Release Notes
</code>

Très proche de la documentation de Stripe.

=== Mode Auteur ===

Accessible uniquement aux équipes internes.

<code>
Documentation Console
</code>

Là, on retrouve une interface d'administration.

Menus :

<code>
Dashboard

Playbooks

Capabilities

Procedures

Templates

Prompts

Publications

Git

Validation

AI Assistant

Settings
</code>

Ce n'est plus un wiki.

C'est un CMS documentaire.

<code>
apps/

documentation-portal/

documentation-console/
</code>

=== 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 ====
<code>
Documentation Repository

↓

Documentation Generator

↓

MkDocs

↓

Documentation Portal

et

Documentation Console

↓

Git

↓

Repository

↓

Generator

↓

Publication
</code>

==== L'IA ====

C'est ici que ça devient intéressant.

Le Documentation Console pourrait avoir un Workspace :

<code>
AI Documentation
</code>

avec :

<code>
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
</code>

En réalité, le développeur ne rédige presque plus.

Il valide.

Et je pense qu'on peut aller encore plus loin...

Je créerais un Documentation Engine, exactement comme tu as maintenant un :

<code>
Notification Engine
Workflow Engine
Search Engine
Theme Engine
</code>

Le Documentation Engine serait un package partagé :

<code>
packages/

documentation-engine/
</code>

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 :

<code>
Documentation Platform
│
├── Documentation Engine (package partagé)
├── Documentation Console (back-office)
└── Documentation Portal (consultation)
</code>

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.

Résumé

Note : En modifiant cette page, vous acceptez que le contenu soit placé sous les termes de la licence suivante : CC Attribution-Share Alike 4.0 International