Documenter plus vite ne sert à rien si la doc devient fausse
Automatiser la documentation n'a de valeur que si le contenu reste vrai après la release suivante. L'IA sait produire vite un README, un résumé d'ADR ou un schéma textuel. Le point dur est ailleurs : savoir quel document mérite d'exister, qui le valide et comment l'obsolescence est détectée.
Une documentation utile réduit le temps d'onboarding, les questions répétitives et les erreurs de compréhension sur les modules critiques. Une documentation volumineuse mais non tenue ajoute simplement une couche de doute.
"L'IA écrit vite, mais seule la propriété documentaire garde le contenu vrai."
La dette documentaire naît souvent après la release
Le danger n'est pas seulement l'hallucination. C'est la documentation plausible qui n'est plus reliée au code, à une décision ou à un propriétaire. Elle rassure au moment où elle est produite, puis devient un piège pour le prochain développeur.
Les risques ne sont pas abstraits. Ils apparaissent dans le quotidien des équipes :
- documentation inventée
- absence de propriétaire
- volume inutile
- écart code-doc
Le coût apparaît à l'onboarding et en incident. Une équipe perd du temps non pas parce qu'il n'y a pas de documentation, mais parce qu'elle ne sait plus quelle documentation croire.
Faire de la documentation un flux vivant, pas un stock mort
La bonne réponse ne consiste pas à générer toute la documentation du dépôt en une fois. Elle consiste à installer une documentation vivante, déclenchée par les changements et reliée aux décisions techniques. Cette approche garde l'ambition, mais elle impose une discipline simple : chaque usage IA doit produire un livrable, une métrique, un propriétaire et une décision explicite de continuation ou d'arrêt.
1. Identifier les documents utiles
Il faut commencer par les documents qui servent vraiment : README de module, ADR actif, parcours d'exploitation, diagramme de dépendances, guide d'onboarding. Tout le reste attend. Le livrable minimal n'est pas un stock complet, mais un README standardisé sur les modules les plus sollicités.
- Décision attendue : choisir le périmètre pilote et ce qui restera hors champ.
- Preuve attendue : une mesure avant déploiement, même imparfaite.
- Anti-pattern : lancer un assistant généraliste sans workflow prioritaire.
2. Générer des brouillons depuis code et ADR
L'IA peut produire un premier brouillon depuis le code, les ADR et l'historique des PR. Mais le brouillon doit afficher ses sources : fichier lu, décision citée, hypothèse à valider. Une documentation qui ne montre pas d'où elle vient est difficile à maintenir.
L'ADR reste le point d'ancrage des décisions. L'agent peut reformuler ou compléter, jamais inventer une justification absente.
3. Faire valider par propriétaire
Chaque document doit avoir un propriétaire. Pas pour signer une page, mais pour arbitrer ce qui est vrai, incomplet ou périmé. Sans propriétaire, l'IA produit ; personne ne maintient.
Les diagrammes textuels sont utiles s'ils sont régénérables et reliés aux conventions de l'équipe. Ils doivent aider à comprendre les dépendances, pas décorer la documentation.
4. Détecter l'obsolescence
Le cas documentaire doit vivre au rythme du code. On le garde si les documents obsolètes diminuent, si l'onboarding s'accélère, si les questions répétitives baissent et si les validations humaines restent régulières. Le livrable de pilotage : journal de changements.
| Étape | Livrable | Signal de qualité |
|---|---|---|
| Cadrage | README standardisé | Baseline documents obsolètes disponible |
| Responsabilité | ADR | Validateur humain nommé |
| Contexte | diagrammes textuels | Sources et droits explicités |
| Pilotage | journal de changements | Décision go/stop à date fixe |
:::
Le point où la doc redevient un actif et non une corvée
La documentation redevient un actif quand les développeurs la consultent sans demander si elle est à jour. Le signal est très concret : moins de questions répétitives, onboarding plus court, corrections plus rapides sur les modules documentés.
Le résultat tient à un flux simple : changement de code, brouillon documentaire, validation propriétaire, détection d'obsolescence. Sans ce flux, l'automatisation produit un stock qui vieillit dès le premier merge.
Un pilote limité qui produit de la documentation encore utile six semaines plus tard
Un bon pilote choisit cinq modules souvent sollicités : ceux qui génèrent des questions, ralentissent l'onboarding ou concentrent les incidents. Chaque document a un propriétaire et une date de revue. Six semaines plus tard, on vérifie s'il est encore consulté et encore exact.
Pour ce thème, le pilote doit contenir cinq éléments :
- un sponsor capable d'arbitrer les priorités ;
- un propriétaire opérationnel du workflow ;
- un jeu de données ou de cas réels relié à diagrammes textuels ;
- une règle claire sur les usages interdits ;
- une date de revue avec décision de continuation ou d'arrêt.
Cette approche évite de documenter tout le dépôt pour ne servir personne.
Les indices qui montrent que la documentation redevient crédible
Les signaux utiles sont rarement spectaculaires : baisse du temps d'onboarding, baisse des questions répétitives, hausse du taux de validation, baisse des documents obsolètes. Ce sont eux qui montrent que la documentation redevient crédible.
Si l'équipe produit davantage de pages sans réduire ces irritants, il faut réduire le périmètre et revenir aux documents vraiment consultés.
Combien de temps faut-il pour obtenir un signal fiable ?
Un premier signal apparaît souvent en 2 à 4 semaines si le workflow est bien borné et si une baseline existe pour la métrique documents obsolètes.
Faut-il commencer par un outil ou par un cas d'usage ?
Par le cas d'usage et par la friction à supprimer. L'outil se choisit ensuite selon le contexte, les droits, les intégrations nécessaires et le niveau de risque.
Comment éviter les gains déclaratifs ?
Mesurez au moins un indicateur avant/après, par exemple documents obsolètes, temps d'onboarding ou questions répétitives, et demandez une preuve opérationnelle.
Quand faut-il arrêter un pilote IA ?
Quand le gain est trop faible, quand le risque résiduel reste trop élevé ou quand l'équipe ne peut pas maintenir le cas sans support disproportionné.
Les documents obsolètes restent le verdict final
Les documents obsolètes restent le verdict final. Une automatisation documentaire utile doit réduire leur nombre, pas seulement accélérer leur création.