La dette de documentation : le passif caché qui plombe vos projets

Il y a une dette dont on parle beaucoup en 2026 : la dette technique. Refactoring repoussé, tests manquants, architecture qui grince. Mais il existe une dette cousine, tout aussi coûteuse et bien moins visible sur un dashboard de qualité de code : la dette de documentation, fonctionnelle autant que technique.

J'ai vu ce cas de figure se répéter, sous des formes différentes mais avec la même mécanique de fond.

Comment on en arrive là

« Shipping first time code is like going into debt » — Ward Cunningham, qui a inventé le terme « dette technique » en 1992, posait déjà le problème : livrer du code non mûri, c'est emprunter. Reste à savoir qui paiera les intérêts, et avec quoi.

La solution grandit sans cadrage produit formel. Une PME lance un MVP, une fonctionnalité en entraîne une autre, un client important demande une exception, puis une autre. Le produit avance à la vitesse du besoin, pas à celle de la documentation. Personne n'a jamais écrit noir sur blanc pourquoi telle règle métier existe — elle vit uniquement dans la mémoire de ceux qui l'ont codée, ou pire, uniquement dans le code lui-même, sous forme de if imbriqués sans commentaire.

Les sachants quittent l'entreprise. Et avec eux part la doc fonctionnelle et technique qui n'a jamais existé ailleurs que dans leur tête. Ce n'est pas une négligence isolée : c'est souvent la conséquence directe du premier point. Quand il n'y a jamais eu de cadrage formel, il n'y a rien à transmettre au départ d'un sachant — sinon un debrief de dernière minute, forcément incomplet.

Ce phénomène n'a rien d'anecdotique. Selon l'enquête 2022 de Stack Overflow menée auprès de plus de 70 000 développeurs, 68 % des développeurs tombent au moins une fois par semaine sur une information dont ils ont besoin... mais qui n'existe nulle part, sauf dans la tête de quelqu'un d'autre. Un chiffre qui grimpe à 73 % chez les managers techniques — souvent les plus expérimentés, donc les plus proches du départ.

68 % des développeurs et 73 % des managers techniques tombent au moins une fois par semaine sur une information dont ils ont besoin mais qui n'existe nulle part, sauf dans la tête de quelqu'un d'autre. — Une information indispensable, absente de partout sauf d'une tête.

Les impacts, au-delà de l'inconfort

Le manque de documentation n'est pas qu'une gêne pour les nouveaux arrivants. Il a des conséquences concrètes et mesurables :

Onboarding qui s'éternise : un nouveau développeur met des semaines à devenir autonome, en reconstituant par archéologie ce qu'une doc aurait transmis en heures.
Régressions fonctionnelles : sans trace des règles métier, on réintroduit des bugs déjà corrigés, ou on casse un comportement qui avait une raison d'être oubliée depuis longtemps.
Décisions produit à l'aveugle : impossible de savoir si une fonctionnalité existe déjà, sous quelle forme, ni pourquoi elle a été conçue ainsi.
Dépendance critique à quelques individus : le bus factor devient un risque business réel, pas juste une private joke d'ingénieur.
Un coût qui s'accumule avec le temps : chaque fonctionnalité ajoutée sans être documentée alourdit un peu plus la dette suivante — comme des intérêts qui s'empilent sur un capital jamais remboursé.

Le temps perdu se chiffre facilement. Toujours selon la même enquête, 62 % des développeurs passent plus de 30 minutes par jour à chercher des réponses ou des solutions, et 25 % y consacrent plus d'une heure — ce qui représente, pour une équipe de 50 développeurs, entre 333 et 651 heures perdues chaque semaine. À l'échelle macro, le Consortium for Information & Software Quality (CISQ) a estimé, dans son rapport 2022 sur la qualité logicielle aux États-Unis, que la mauvaise qualité logicielle coûtait 2 410 milliards de dollars, dont 1 520 milliards imputables à la seule dette technique. La documentation manquante n'est évidemment pas l'unique cause de ce chiffre, mais elle en est un contributeur direct et documenté.

62 % des développeurs perdent plus de 30 minutes par jour à chercher des réponses, 25 % plus d'une heure, soit 333 à 651 heures perdues chaque semaine pour une équipe de 50 développeurs. Sur les 2410 milliards de dollars que coûte la mauvaise qualité logicielle aux États-Unis, 1520 milliards sont imputables à la dette technique. — Le manque de documentation se chiffre, en heures perdues comme en dollars.

Comme le résume Damian Conway, auteur de Perl Best Practices : « Documentation is a love letter that you write to your future self » — une documentation, c'est une lettre d'amour qu'on s'écrit à soi-même dans le futur. Faute de l'avoir écrite, c'est toute l'équipe suivante qui en paie l'absence.

Même à l'heure de l'IA, la doc reste indispensable

On pourrait penser que l'essor des agents de code change la donne, ou même rend la doc obsolète puisque l'IA « comprend » le code. C'est l'inverse qui se produit.

Un agent de code ou de QA n'a pas d'intuition métier. Il ne sait pas pourquoi une règle existe, seulement ce que le code fait littéralement. Une documentation fonctionnelle et technique de qualité, passée en contexte ou indexée en RAG, améliore considérablement l'efficacité de ces agents : moins d'hallucinations sur l'intention métier, des suggestions de code plus pertinentes, une revue de QA capable de distinguer un vrai bug d'un comportement voulu. La doc n'a pas perdu de valeur avec l'IA — elle en a gagné, parce qu'elle devient la mémoire structurée que l'agent consulte à chaque tâche.

RetroDoc : reconstruire la doc manquante

J'interviens régulièrement chez mes clients pour résoudre leurs problèmes de dette technique, mais aussi pour les accompagner dans l'intégration efficace de l'IA à leur métier. Et sur le terrain, le constat est sans appel : le manque de documentation ne freine pas seulement leurs équipes, il a un impact direct sur mes propres missions. Chaque heure passée à reconstituer manuellement le contexte fonctionnel d'une application est une heure en moins pour résoudre le vrai problème.

C'est ce constat qui m'a poussé à créer RetroDoc, et plus largement une panoplie d'outils pensés pour ça, en m'appuyant sur ma longue expérience du développement logiciel et de la dette technique, combinée à mon savoir-faire en intégration d'IA agentique. RetroDoc s'appuie sur le code source, l'historique des tickets et les quelques documents épars encore disponibles pour reconstruire a posteriori la documentation fonctionnelle et technique qui n'a jamais été écrite — ou qui s'est perdue avec le départ des sachants.

L'idée n'est pas de remplacer la discipline de documenter au fil de l'eau, mais de traiter le passif existant : redonner à une équipe une base de connaissance exploitable, à la fois pour les humains qui rejoignent le projet et pour les agents IA qui vont désormais y travailler à leurs côtés.

Code source, historique des tickets et documents épars alimentent RetroDoc, qui reconstruit une base de connaissance exploitable à la fois par les humains et par les agents IA. — RetroDoc reconstruit a posteriori ce qui n'a jamais été écrit.

Je partagerai l'avancement de RetroDoc dans un prochain article.

Sources : Stack Overflow Developer Survey 2022 · CISQ, Cost of Poor Software Quality in the US: A 2022 Report