On a appris à notre IA à écrire notre documentation (et elle le fait mieux que nous)
Soyons honnêtes : personne n'aime écrire de la documentation. On le fait au lancement du projet, plein de bonnes intentions... puis plus jamais. Six mois plus tard, la doc dit une chose, le code en fait une autre, et les utilisateurs perdent un temps précieux à comprendre pourquoi rien ne fonctionne comme prévu.
On s'est dit : "Et si on automatisait tout ça ?" Alors on l'a fait. Et les résultats ont dépassé nos attentes.
Le problème qu'on voulait résoudre
Chez téo, notre application évolue constamment pour répondre aux besoins de nos utilisateurs : organismes de formation, consultants, structures d'accompagnement. Chaque sprint apporte son lot de nouvelles fonctionnalités — un nouveau champ dans les dossiers, une option supplémentaire pour les questionnaires, une amélioration du suivi des bénéficiaires.
Le problème ? À chaque évolution du produit, la documentation doit suivre. Sinon, un utilisateur qui cherche "comment créer un questionnaire de satisfaction" trouve un guide qui ne correspond plus à l'interface actuelle.
Résultat :
- 😤 L'utilisateur perd du temps à comprendre les différences
- 🔄 Il contacte le support ou son téomaster pour une question qui devrait être documentée
- 📉 La documentation perd sa crédibilité
Ce scénario, on l'a vécu des dizaines de fois. La documentation manuelle, ça ne tient pas sur la durée.
Notre solution : une IA qui surveille le code
On a construit un système qui fait le travail à notre place. À chaque modification du code, il :
- Détecte ce qui a changé
- Comprend l'impact sur la documentation
- Réécrit les sections concernées
- Vérifie que tout est cohérent
- Applique les modifications
Le tout en 2-3 minutes, là où un humain mettrait des heures (si tant est qu'il y pense).
Un exemple concret
Imaginons qu'un développeur ajoute un bouton "Signature électronique" sur les documents de téo. Ce bouton permet désormais d'envoyer un document à signer directement depuis un dossier.
Sans notre système :
- Le développeur fait son commit
- La documentation des documents reste inchangée
- Les utilisateurs découvrent la fonctionnalité par hasard ou contactent le support
Avec notre système :
🔍 Changement détecté : document-actions.ts, signature-button.ts
📖 Documentation impactée : docs/dossiers/documents.md
✏️ Mise à jour : section "Actions sur les documents" enrichie avec "Signature électronique"
✅ Validation OK - Documentation synchronisée !
C'est automatique. Personne n'a rien eu à faire.
Comment ça marche
On utilise une approche qu'on appelle RAG (Retrieval Augmented Generation, ou "génération augmentée par la recherche"). Le principe : on ne demande pas à l'IA d'inventer des choses. On lui montre exactement le code qui a changé, et elle en déduit ce qu'il faut écrire.
Le workflow complet
La recherche intelligente dans le code
Une de nos fonctionnalités clés : on peut demander à l'IA de trouver du code simplement en le décrivant.
# "Trouve-moi tout ce qui touche aux questionnaires"
npm run test:search "système de questionnaires avec envoi par email"
# Résultat :
✅ 12 fichiers trouvés :
- questionnaire/questionnaire.service.ts
- questionnaire/email-sender.ts
- models/questionnaire-response.ts
...
Pas besoin de connaître les noms des fichiers. On décrit ce qu'on cherche, l'IA trouve.
Aller plus loin : AskAI pour la recherche utilisateur
Générer une documentation à jour, c'est essentiel. Permettre aux utilisateurs de trouver facilement ce qu'ils cherchent, c'est encore mieux.
C'est pourquoi on a intégré AskAI d'Algolia directement dans notre centre d'aide téo.
Comment ça fonctionne
Au lieu de taper des mots-clés et parcourir des résultats, nos utilisateurs posent des questions en langage naturel et obtiennent des réponses directes.
👤 "Comment créer un dossier pour un nouveau bénéficiaire ?"
🤖 "Pour créer un dossier, rendez-vous dans la section Dossiers,
cliquez sur 'Nouveau dossier', puis renseignez les informations
du bénéficiaire..."
📎 Sources : guide/dossiers.md, tutos/premier-dossier.md
Les avantages concrets
🎯 Pour nos utilisateurs :
- Réponses instantanées : plus besoin de lire plusieurs pages pour trouver une info
- Langage naturel : on pose sa question comme on la poserait à son téomaster
- Contexte préservé : l'IA comprend les questions de suivi
- Sources citées : chaque réponse renvoie vers la documentation officielle
📈 Pour nous :
- Réduction des sollicitations support : les utilisateurs trouvent leurs réponses seuls
- Insights précieux : on voit quelles questions sont posées le plus souvent
- Documentation vivante : les questions sans réponse nous indiquent ce qu'il manque
- Expérience premium : une documentation qui répond vraiment aux besoins
Le cercle vertueux
Ce qui rend notre approche puissante, c'est la combinaison des deux systèmes :
La documentation est générée automatiquement ET consultable intelligemment. C'est le meilleur des deux mondes.
Les enseignements clés
1. Le code ne ment pas (mais il ne dit pas tout)
Le code donne la vérité technique, mais pas toujours le pourquoi métier. L'échange avec les utilisateurs reste indispensable pour comprendre leurs besoins réels et traduire les fonctionnalités en documentation utile.
2. La documentation doit vivre avec le code
En s'appuyant sur les vrais noms de menus, états et champs présents dans le code, on évite la dérive entre documentation et réalité. C'est la clé d'une doc toujours à jour.
3. L'IA a besoin de contexte
On ne peut pas juste dire "mets à jour la doc". Il faut montrer à l'IA exactement quel code a changé et comment fonctionne la documentation actuelle. Plus le contexte est précis, meilleur est le résultat.
4. La validation reste essentielle
L'IA peut parfois produire du contenu inadapté. On a mis en place des garde-fous :
- Le contenu généré est-il suffisamment complet ?
- Les liens fonctionnent-ils ?
- La syntaxe est-elle correcte ?
- Le build Docusaurus passe-t-il ?
Si quelque chose ne va pas, on annule tout automatiquement.
Notre stack technique
| Composant | Technologie | Rôle |
|---|---|---|
| Génération | Gemini 2.5 Flash | Analyse du code et rédaction |
| Orchestration | Firebase | Exécution serverless et scalable |
| Cache | Firestore | Mémoire partagée entre instances |
| Recherche code | GitLab API + ripgrep | Indexation ultra-rapide |
| Documentation | Docusaurus | Publication et rendu |
| Recherche IA | Algolia AskAI | Assistance conversationnelle |
Ce que ça change au quotidien
Avant, mettre à jour la documentation était cette tâche ingrate que tout le monde repoussait. Maintenant :
- L'équipe produit fait évoluer téo sereinement — la documentation suit automatiquement
- Les nouveaux utilisateurs ont une documentation fiable dès le premier jour
- Les utilisateurs existants trouvent leurs réponses en quelques secondes grâce à AskAI
- Les téomasters se concentrent sur l'accompagnement plutôt que sur les questions basiques
En résumé
On a construit un écosystème complet qui :
- ✅ Surveille notre code en permanence
- ✅ Génère la documentation automatiquement
- ✅ Vérifie que tout est correct
- ✅ Publie sur notre centre d'aide
- ✅ Répond aux questions des utilisateurs via AskAI
La documentation obsolète et la recherche laborieuse, c'est terminé.
🔍 Envie de tester ? Posez une question à notre assistant IA directement sur ce centre d'aide — cliquez sur l'icône de recherche en haut à droite et voyez par vous-même !
Vous avez des questions sur notre approche ? Un projet similaire en tête ? Échangeons — on aime partager sur ces sujets ! 💬