Pendant quinze ans, obtenir de la documentation d’une équipe de développement a relevé du combat. On la réclamait en revue, on la posait dans le backlog, elle n’arrivait jamais. Le README avait trois ans, le schéma d’architecture décrivait un système refactoré deux fois depuis, et l’essentiel vivait dans la tête de deux personnes qu’il fallait intercepter entre deux réunions.

Ce problème est réglé. Depuis un peu plus d’un an, je vois passer — chez mes clients comme dans mes propres projets — des documentations complètes, bien structurées, à jour de la dernière refonte. Des pages et des pages. Souvent plus qu’il n’y a de code à lire.

Et c’est pire.

On a confondu le volume avec la connaissance#

Rien d’accidentel là-dedans. Quand le coût de production d’une chose s’effondre, on n’en produit pas la même quantité moins cher : on en produit infiniment plus. Ce fut vrai du charbon, de la bande passante, et c’est vrai de la page de documentation. Écrire vingt pages ne coûte plus rien, alors on écrit vingt pages.

Sauf que ce qui remplit ces pages était, la plupart du temps, déjà dans le code. Un commentaire qui annonce que la fonction getUserById récupère un utilisateur par son identifiant n’apprend rien à personne : il paraphrase la signature. Cinq paragraphes impeccablement formatés qui ne disent ni à quoi sert le module, ni sous quelles contraintes il a été écrit, ni où sont les pièges, n’apprennent rien non plus. Et le pourquoi — pourquoi ce cache, pourquoi ce compromis, quelle alternative a été écartée et pour quelle raison — reste invariablement absent. Il n’a jamais été dans le code. Il est dans la tête des gens.

J’ai un test simple, un peu brutal : supprimez la page. Si personne ne s’en aperçoit dans les six mois, il n’y avait rien dedans.

On répète depuis vingt ans qu’une documentation en retard est un problème de motivation. C’était faux, c’était un problème d’outillage. L’IA a réglé l’outillage — et nous a démontré que le sujet n’avait jamais été ni l’un ni l’autre.

Le vrai coût, ce n’est pas le temps perdu, c’est la confiance#

Un développeur ouvre une page et y trouve une méthode qui n’existe pas. Un paramètre de configuration inventé de toutes pièces, une option jamais implémentée. Il perd une demi-heure à chasser un fantôme. Ce n’est pas grave.

Ce qui est grave, c’est ce qu’il fait ensuite : il arrête de faire confiance à la documentation. Pas à cette page-là — à toute la documentation, y compris aux quatre-vingts pour cent qui étaient exacts. Et cette confiance-là ne se reconstruit pas par décret.

La boucle se referme alors proprement. On documente pour que l’information circule ; la documentation invérifiable produit l’inverse exact : plus personne ne lit, et on retourne demander à deux personnes entre deux réunions. Retour au point de départ, avec en prime un stock de pages à maintenir. Chaque page inutile a relevé le niveau du bruit d’un cran.

Les chiffres disponibles ne portent pas sur la documentation mais sur le contenu de travail généré en général, et ils suffisent. Des chercheurs de BetterUp Labs et du Social Media Lab de Stanford ont mis un nom sur ce contenu qui a l’apparence du travail sérieux sans en avoir la substance : le workslop. Leur enquête avance une heure et cinquante-six minutes en moyenne pour rattraper chaque incident, et surtout une chute de 42 % de la confiance accordée à celui qui l’a produit. Ces chiffres sont déclaratifs et leur méthode a été discutée ; l’ordre de grandeur, lui, correspond à ce que je constate.

Côté production, l’asymétrie est plus parlante encore : générer quarante pages prend une heure, les relire sérieusement prend une semaine. Vérifier une affirmation plausible coûte plus cher que de l’écrire soi-même. Le coût n’a pas disparu — il s’est déplacé, et il a grossi.

Reste à comprendre pourquoi rien ne filtre. La réponse est désagréable : nos garde-fous ne regardent pas là. Une revue de code traque les erreurs de code. Personne ne relit les commentaires, même quand ils sont faux. C’était déjà vrai avant l’IA, à ceci près qu’il y en avait dix fois moins.

Écrire pour qui, au fait ?#

Il y a dans cette histoire une ironie que je trouve savoureuse. Cette documentation que plus personne ne lit, on la lit quand même — avec une IA. On demande à un agent de résumer les pages qu’un agent a écrites.

Ce n’est plus une anecdote : d’après les chiffres publiés par GitBook, 41 % des requêtes sur les pages de documentation proviennent désormais d’agents. Un standard est même né pour ça, llms.txt, proposé en 2024 : un fichier qui indique aux modèles quoi lire dans votre documentation. Certaines plateformes vont plus loin et proposent des balises pour du contenu réservé aux agents, que les humains ne verront jamais.

Et que recommandent les guides de rédaction qui accompagnent ce mouvement ? Des listes plutôt que des pavés, des paragraphes courts, pas de remplissage. Exactement ce qu’il aurait fallu faire depuis toujours pour nos collègues. Sauf que cette fois, c’est pour le confort de la machine.

Certains en tirent la conclusion inverse de la mienne : puisque les agents consomment la documentation, en produire massivement deviendrait un avantage. Je n’y crois pas une seconde. Un agent ne compense pas l’absence d’intention, il la propage — plus vite, et à plus grande échelle. On ne construit pas une base de connaissances, on entraîne une machine à répéter ses propres approximations.

Le TL;DR que personne ne peut écrire à ma place#

Voici ce que je fais désormais, et ça tient en une règle. Avant de générer une seule ligne de documentation, j’écris l’en-tête moi-même : un TL;DR de trois ou quatre phrases, avec mes mots, sans assistance.

Ça paraît dérisoire. Ça change trois choses.

Ça donne une direction. Un modèle à qui l’on demande de documenter un module produit un inventaire ; le même modèle, à qui l’on donne d’abord l’intention en trois phrases, produit un texte qui va quelque part.

Ça fait apparaître mes propres erreurs. Résumer un composant avec ses mots, c’est découvrir qu’on avait mal lu une condition, ou qu’on ne sait pas expliquer un choix qu’on croyait maîtriser. Cette gêne de dix minutes est le meilleur retour sur investissement de la journée.

Ça rend la page consommable telle quelle. Un collègue lit quatre phrases écrites par un humain, comprend, et n’a pas besoin de faire résumer le reste par un agent.

Un mot sur la verbosité, parce que ma première réaction a été naïve : je demandais dans mes prompts d’être concis, d’éviter les pavés. C’est du bricolage. Chacun son prompt, chacun son style, quarante pages en quarante voix. La contrainte doit être structurelle — un guide de style et des gabarits injectés dans chaque génération, au même endroit pour tout le monde. Et pour les décisions qui structurent un système, il existe un format plus solide que le TL;DR, qui a vingt ans et n’a pas attendu l’IA : l’ADR, une page par décision, contexte, décision, conséquences.

Le plancher de bruit#

En audio, le plancher de bruit désigne le niveau du bruit de fond sous lequel un signal devient indétectable. Il n’efface rien : il noie. Nous n’avons pas dégradé notre documentation, nous avons relevé le plancher jusqu’à ce que la bonne devienne introuvable au milieu de l’autre.

L’IA ne remplace pas l’expertise, elle l’amplifie — dans les deux sens. Ces quatre phrases que j’écris à la main ne sont pas la corvée qui subsiste après l’automatisation : c’est le seul endroit où j’apporte encore quelque chose. Tout le reste, la machine le fait mieux que moi, plus vite, et pour presque rien.

C’est aussi tout le reste qui fait du bruit.

Sources#