La documentation, on la connaît
On a tous nos excuses favorites. « On n'a pas le temps. » « C'est dans Confluence. » « On fera ça plus tard. » « Le code est auto-documenté. »
Et pendant ce temps, ce qui se passe réellement : le nouvel arrivant n'a personne pour l'onboarder, Confluence est obsolète et hors-sync, l'architecture a changé sans que personne ne mette à jour les docs.
La documentation est souvent traitée pire que la couverture de tests. Au moins les tests, on les mesure.
Avec les assistants IA de code, ce problème change de nature. Il s'accélère. Et une nouvelle conséquence s'ajoute à la liste : l'assistant a accès au code, mais pas au contexte. Il voit le quoi, pas le pourquoi. Sans documentation, il comble les lacunes par des hypothèses.
Le problème des sessions stateless
Chaque session d'un assistant IA de code démarre sans mémoire des conversations précédentes. Ce n'est pas un bug, c'est une contrainte fondamentale.
Ce qui persiste entre les sessions, pour tout le monde : le code (fonctions, tests, config, structure, git), la documentation versionnée dans le dépôt, et le fichier AGENTS.md qui contient les instructions projet.
Ce qui persiste, mais seulement pour moi : certains agents disposent d'une mémoire locale qui survit entre les sessions. Mais elle ne vit que sur ma machine. Mes collègues n'y ont pas accès, elle n'est pas versionnée, elle ne voyage pas avec le projet.
Ce qui disparaît à la fermeture : le contexte de session (raisonnements, décisions, tentatives) et surtout le savoir oral. Tout ce que j'explique en call ou sur Slack et qui n'est pas écrit quelque part, l'assistant n'y aura jamais accès.
Conséquence directe : sans documentation, chaque développeur réinvente ce que le précédent avait déjà résolu dans sa propre session. Chaque session repart de zéro, pose les mêmes questions, prend les mêmes risques de diverger du design réel.
L'absence de documentation crée de la dette technique d'un nouveau genre. Pas de code legacy difficile à refactorer, mais des hallucinations, des décisions prises sur des bases obsolètes, et une dérive progressive du code produit par l'IA par rapport au système réel.
La trace écrite
L'assistant lit ce qui est disponible. Sans documentation, il comble le reste par des hypothèses.
La documentation n'est plus seulement utile aux humains qui rejoignent le projet. Elle est le grounding de l'assistant, l'ancrage dans la réalité du projet qui lui permet de prendre des décisions alignées plutôt que d'inventer.
Un dossier docs/ bien structuré à la racine du dépôt devient la mémoire partagée entre toutes les sessions, entre tous les développeurs, entre l'humain et l'IA.
Ce que j'ai aussi constaté en pratique : écrire de la documentation est devenu beaucoup plus simple. Avant, la friction était réelle : trouver le bon niveau de détail, structurer une page de référence, rédiger un ADR après coup. Avec un assistant IA, je décris le contexte, et la documentation prend forme. Je relis, j'ajuste, je valide. Le temps de rédaction s'effondre.
L'assistant peut également auditer l'existant. Des outils comme /diataxis (qui analyse, classifie et restructure la documentation existante) font partie des skills disponibles pour Claude, des extensions de comportement installables en une commande :
npx skills add https://github.com/rlespinasse/agent-skills --skill diataxis
La structure avant tout
Écrire, c'est bien. Mais si tout atterrit dans un README de 500 lignes qui mélange guide d'installation, architecture, API, et troubleshooting, ni l'humain ni l'IA ne s'y retrouvent.
C'est là que Diataxis (un framework de documentation créé par Daniele Procida que j'utilise depuis bien avant l'ère des LLMs) a pris une nouvelle dimension. J'en montre une application concrète dans l'anatomie d'un side project drôle fait sérieusement. Il identifie 4 types de besoins d'information distincts :
- Tutorials : apprentissage pas-à-pas, orienté vers l'action guidée. L'onboarding d'un nouveau développeur.
- How-to guides : procédures pour atteindre un objectif précis. Guide de déploiement, procédure de release.
- Reference : information factuelle à consulter. API, variables d'environnement, table des rôles.
- Explanation : compréhension des trade-offs et du contexte. Architecture decision records, choix techniques.
Ces 4 catégories correspondent à 4 besoins réellement différents. Les mélanger dans un même document rend celui-ci inutilisable : on cherche une procédure et on tombe sur de l'architecture, on cherche une valeur de configuration et on se retrouve dans un tutoriel.
Ce que Diataxis change pour les LLMs
Ce framework, conçu pour les humains, fonctionne remarquablement bien pour les assistants IA. Ce n'est pas un hasard, c'est une conséquence directe de ce qui fait sa force : séparer les besoins d'information.
| Catégorie | Pour l'humain | Pour l'assistant IA |
|---|---|---|
| Tutorials | Onboarding pas-à-pas | Non utilisé (l'IA n'apprend pas) |
| How-to | Procédure de release | Exécuté étape par étape |
| Reference | Lookup de rôles, config | Extraction de faits pour décisions |
| Explanation | Comprendre les trade-offs | Contexte avant modification |
Une documentation structurée selon Diataxis sert les deux audiences sans effort supplémentaire. La seule exception : les tutorials, catégorie 100% humaine. L'IA n'a pas besoin d'apprendre à faire quelque chose, elle a besoin de faits pour décider.
La reclassification comme signal de maturité
L'un des effets que j'ai trouvés les plus intéressants : le framework révèle les pages mal classifiées.
Un troubleshooting rangé dans how-to/ parce qu'il « ressemble à de l'aide » est en réalité une table de lookup (symptôme, fix). C'est de la reference/. L'humain scanne plus vite, l'IA extrait les paires symptôme/solution directement.
Une page « Gestion des accès » qui mélange la liste des rôles et la procédure d'attribution sert mal les deux besoins. Découpée en deux pages distinctes (une table de référence et un guide procédural), chaque audience trouve ce qu'elle cherche.
L'effet composé
Le vrai effet de la documentation structurée n'est pas immédiat. Il se révèle dans le temps.
La boucle fonctionne ainsi : je demande à l'assistant de produire de la documentation lors d'une session. Cette documentation persiste. À la session suivante, l'assistant la lit avant d'agir. Il prend de meilleures décisions, alignées avec le design réel. Ces décisions amènent à mettre à jour la documentation. Et le cycle recommence.
Chaque page de documentation rend toutes les sessions futures meilleures.
Sans structure, cette boucle ne fonctionne pas. Avec un dossier plat de fichiers Markdown sans organisation claire, l'assistant ne sait pas s'il doit lire le troubleshooting ou l'ADR d'architecture avant de modifier un composant. Diataxis donne à chaque catégorie un usage clair : l'IA sait où chercher et où écrire.
L'effet composé se manifeste concrètement, d'abord pour moi :
- Jour 1 : dans ma session, l'assistant produit
architecture.md,deploy-guide.md,adr-001.mden même temps que le code. Investissement initial. - Deux semaines plus tard, dans ma propre session : je reprends le projet après une coupure. L'assistant relit la documentation et me recontextualise sans que j'aie à tout réexpliquer. La décision d'architecture prise il y a deux semaines est toujours là, accessible.
Et ensuite pour l'équipe :
- Un collègue ouvre sa propre session : l'assistant lit
architecture.mdavant de modifier le pipeline. Le changement est aligné avec le design, sans que mon collègue ait eu à me demander quoi que ce soit. - Un nouveau développeur rejoint l'équipe : il ouvre sa première session. L'assistant a accès à toute la documentation accumulée et peut répondre aux questions de contexte sans session d'onboarding.
Sans documentation, chaque développeur réinvente ce que le précédent avait déjà résolu dans sa propre session. Et moi-même, je réinvente ce que j'avais résolu deux semaines plus tôt. Zéro capitalisation.
En pratique
Voici comment j'aborde ça sur mes projets, en trois étapes :
Étape 1 : Installer les skills Diataxis
npx skills add https://github.com/rlespinasse/agent-skills --skill diataxis
Étape 2 : Lancer une analyse de l'existant
Dans une session Claude Code : « Analyse la documentation de ce projet avec le framework Diataxis »
L'assistant scanne, classifie, propose une restructuration, et demande mon approbation avant d'agir.
Étape 3 : Intégrer la documentation dans le flux de travail
Lors de chaque session significative, je demande à l'assistant de mettre à jour ou créer la documentation correspondante. Ce qui va dans CLAUDE.md (les instructions projet versionnées), ce qui va dans docs/reference/ (les faits), ce qui va dans docs/explanation/ (les décisions d'architecture).
Conclusion
La documentation a toujours été importante. Avec les assistants IA de code, elle devient critique, non plus seulement pour les humains qui rejoignent le projet, mais comme condition de fonctionnement correct de l'IA elle-même. Et pour la première fois, l'excuse « on n'a pas le temps » tient moins bien : écrire de la documentation avec un assistant est devenu une tâche de minutes, pas de jours.
Diataxis n'est pas un framework que j'ai adopté pour les LLMs. Je l'utilisais déjà pour structurer la documentation à destination des humains. Ce que j'ai découvert, c'est que cette même structure sert les assistants IA sans rien changer, parce que les besoins d'information sont les mêmes.
La trace écrite. Capturer le savoir avant qu'il ne vive que dans une session fermée.
La structure avant tout. Séparer les besoins d'information pour que chaque audience trouve ce qu'elle cherche.
L'effet composé. Chaque page de documentation rend toutes les sessions futures meilleures.
