Tous les articles
Documentation et changements8 min de lecture

Dérive documentaire : pourquoi toute base de connaissance finit-elle obsolète ?

Pour celles et ceux qui, au produit et au support, tiennent un centre d'aide ou un wiki : la dérive documentaire est une mécanique, pas une négligence. Ses quatre formes, comment la détecter, et quoi demander au lieu de réécrire plus vite.

L'équipe DeployIt

Nous construisons DeployIt, un serveur MCP qui permet à toute une entreprise d'interroger son code depuis Claude et de suivre le travail de chaque développeur.

La dérive documentaire est l'écart qui se creuse entre ce que dit votre documentation et ce que fait votre produit ; c'est elle qui fait que toute équipe se retrouve avec une base de connaissance obsolète. Ce n'est pas un défaut de discipline : un texte figé le jour de sa rédaction décrit un code qui change à chaque release. La sortie n'est pas d'écrire plus vite. C'est de demander au code, au moment de la question, les faits qui changent.

Cette page s'adresse à celles et ceux qui, au produit et au support, tiennent un centre d'aide, un wiki ou des réponses types, et qui sont las d'apprendre par un client qu'une page est fausse.

Dans votre Claude · exemple

Notre page d'aide dit que les exports utilisent la virgule comme séparateur. Est-ce encore vrai ?

Plus maintenant. Un export utilise le point-virgule par défaut.

Un compte peut encore choisir la virgule dans ses réglages d'export. La page d'aide présente ce choix comme la valeur par défaut.

Vérifié dans le code3 fichiers consultés · aucune ligne montrée

Qu'est-ce que la dérive documentaire ?

La dérive documentaire (en anglais, docs drift) est l'écart entre ce qu'une documentation affirme et ce que le produit fait réellement, à mesure que le code évolue et que le texte ne suit pas. Elle commence à la première release qui suit la rédaction.

Elle ne se voit pas. Une page obsolète a la même mise en forme, le même ton assuré et la même place dans les résultats de recherche qu'une page juste. C'est ce qui la rend coûteuse.

Pourquoi toute base de connaissance finit-elle obsolète ?

Trois faits y suffisent, et aucun n'est une négligence.

Le premier : la documentation est écrite une fois, le code change en continu. Une équipe qui met en production plusieurs fois par semaine ouvre à chaque fois un écart possible avec des dizaines de pages rédigées des mois plus tôt. Personne ne sait lesquelles.

Le deuxième : un changement de code ne signale pas la page qu'il rend fausse. Exemple : le développeur qui modifie le séparateur par défaut d'un export ignore que trois articles d'aide, un guide d'intégration et deux réponses types le citent.

Le troisième : la relecture ne passe pas à l'échelle. Relire une page prend quelques minutes ; relire toutes les pages à chaque release est un métier à plein temps que personne n'a budgété.

Il n'y a aucun coupable. Il y a une source qui bouge et une copie qui ne bouge pas.

Quelles sont les quatre formes de la dérive ?

La dérive a quatre visages, et ils ne se repèrent pas de la même façon. Les exemples sont illustratifs.

FormeCe que dit la pageCe que fait le produitComment on le découvre
Le changement silencieux« L'export utilise la virgule »Le séparateur par défaut est désormais le point-virguleUn ticket : « mon import échoue »
La demi-vérité« Les webhooks sont renvoyés trois fois »Toujours trois fois, mais avec un délai croissant et une signatureUn intégrateur dont la vérification casse
Le fantômeUne page entière sur une optionL'option a été retirée ; la page reste indexéeUn prospect demande une fonction disparue
L'angle mortRienUne fonction livrée il y a un mois, jamais documentéeLe support tombe dessus ; les clients, jamais

Le changement silencieux est le mieux connu. La demi-vérité est la plus dangereuse, parce qu'elle survit à la relecture : la phrase reste vraie mot à mot. Le fantôme fait perdre du temps à des gens qui ne sont pas encore clients. L'angle mort n'est pas une erreur dans la doc : c'est une absence, et aucune relecture ne détecte une absence.

Que coûte une base de connaissance obsolète ?

Elle coûte deux fois. D'abord en tickets : celui qui n'aurait pas dû exister, la réponse du support qui contredit la page, le client qui conclut « leur doc est fausse, autant demander ». Chaque page obsolète finit en interruption d'un développeur, la seule personne qui sait ce que fait le code. Cet enchaînement est décrit dans comment réduire les interruptions des développeurs par le support.

Ensuite en confiance. Après quelques réponses périmées, le support cesse de croire les pages qui ont raison. Et tout assistant qui lit la page, bot de support ou recherche interne, la répète avec la même assurance : il ne sent pas qu'une page a l'air vieille.

Un responsable par page et une revue trimestrielle suffisent-ils ?

Donner un responsable à chaque page et la relire chaque trimestre est la réponse d'organisation la plus sérieuse, et elle réduit la dérive. Gardez-la pour les pages qui racontent. Sa limite est arithmétique : la revue est trimestrielle, les releases sont hebdomadaires ou quotidiennes, et une page peut donc rester fausse pendant l'essentiel d'un trimestre avant que quelqu'un la regarde.

Elle n'attrape ni l'angle mort (on ne relit pas une page qui n'existe pas) ni la demi-vérité (la phrase relue est toujours vraie). Tenir la documentation dans le dépôt, avec une PR à chaque changement, fait mieux sur le changement silencieux, tant que le relecteur pense à la page. Cela ne dit rien de ce qui vit hors du dépôt : le centre d'aide public, les réponses types du support.

Comment détecter la dérive documentaire ?

Partez des changements, pas des pages. Trois passes après une release, toutes trois dans Claude :

  1. Listez ce qui est arrivé. « Qu'est-ce qui a changé ces 14 derniers jours ? » La liste revient regroupée en livraisons, chacune avec sa date et son titre : voir ce qui a changé cette semaine.
  2. Retrouvez les pages qui décrivent ces parties. Une livraison sur les exports désigne les pages d'export, le guide d'import et les réponses types qui les citent.
  3. Vérifiez chaque phrase factuelle. « Quel séparateur les exports utilisent-ils par défaut ? » La réponse dit ce que fait le code aujourd'hui, avec un statut.

L'angle mort apparaît à la première passe : la fonction que personne n'a documentée est dans la liste, parce que la liste est bâtie sur ce qui est arrivé. Le fantôme apparaît à la troisième : une option retirée revient « Introuvable » au lieu d'être décrite avec assurance.

Pour mesurer votre propre dérive, tirez dix pages au hasard et vérifiez leurs phrases factuelles. Le nombre de pages qui portent au moins une phrase fausse donne un taux de dérive approximatif. C'est le vôtre, pas une référence.

Le wiki dit une chose, le code une autre : lequel croire ?

Cela dépend de ce dont parle la phrase.

Sur ce que fait le produit (une limite, une valeur par défaut, une règle), croyez le code, quand la réponse revient « Vérifié ». Sur la raison d'un choix, sur qui décide, sur la façon de travailler de l'équipe, croyez le wiki : le code ne contient aucune décision.

Quand les deux divergent sur un comportement, il y a deux possibilités. La page est périmée, ou le code a un défaut et la page dit ce qui était voulu. Le code ne peut pas vous dire laquelle : c'est à une personne de trancher.

Que faire d'une base de connaissance obsolète ? Interroger le code

Tant que la documentation est une copie du produit écrite à la main, elle dérive : c'est la nature d'une copie. Réécrire la copie plus vite ne fait que raccourcir le décalage. Faire écrire la copie par une machine donne une autre copie, avec le même problème de date. Ce qui supprime le décalage, c'est de cesser de tenir la copie pour la source des faits qui changent, et d'interroger le code quand la question se pose.

DeployIt est un serveur MCP. Votre entreprise a un lien, https://mcp.deployit.ai/<entreprise>/<code> ; chacun l'ajoute à son Claude (web, bureau ou Claude Code) et s'inscrit avec un nom et un e-mail, qui n'est pas vérifié ; ses questions sont journalisées sous ce nom. Tout le monde commence avec le profil « Tout le monde » : des questions sur le produit, répondues depuis le code ; un filtre retire des réponses le code, les chemins de fichiers et les noms des membres de l'équipe qu'il reconnaît, sans prouver leur absence, et un test de fuite vous dit ce qui passe encore. Un administrateur donne le profil « Développeurs » (des extraits) ou « Direction » (les statistiques des développeurs) à qui en a besoin. Les dépôts se connectent depuis GitHub ou GitLab ; DeployIt n'y fait ni commit, ni branche, ni PR, et y pose seulement un webhook par dépôt.

DeployIt n'écrit aucune page : ni documentation, ni changelog, ni article d'aide. ask_code répond depuis le code à une question de comportement et donne un statut à sa réponse (Vérifié, Côté serveur seulement, Introuvable ou Sans conclusion : voir lire une réponse). recent_changes liste ce qui est arrivé sur une période. La personne qui tient la page lit la réponse et corrige le texte.

Ce qui s'écrit à la main garde toute sa valeur : le pourquoi d'une décision, le ton, le parcours d'un nouvel arrivant. Ce qui passe au code, c'est la vérification du quoi et du comment, la partie qui change à chaque release.

Voir comment fonctionne DeployIt, profil par profil ; les exemples du support et du produit sont sur la page d'accueil. Pour les questions que le produit envoie aux développeurs, voir interroger votre base de code avant de déranger un développeur.

Prochaine étape : ajoutez l'adresse de démonstration ci-dessous aux connecteurs de votre Claude et posez-lui une question ; puis connectez vos dépôts, ajoutez le lien de votre entreprise à Claude en trois étapes, ouvrez votre page d'aide la plus consultée et vérifiez sa première phrase factuelle.

Prix. Plan gratuit : 15 questions par semaine pour toute l'entreprise. Essai de 30 jours, sans carte. Forfaits à partir de 290 € HT par mois pour 25 développeurs suivis : voir le tarif.

Interrogez votre code depuis Claude

Essai de 30 jours, sans carte. Ou essayez d'abord la démonstration : ajoutez https://mcp.deployit.ai/demo aux connecteurs de votre Claude.

Connecter mon code

Questions fréquentes

Qu'est-ce que la dérive documentaire ?

La dérive documentaire (docs drift) est l'écart qui se creuse entre ce qu'une documentation affirme et ce que fait le produit, à mesure que le code change et que le texte ne suit pas. Elle commence à la première release qui suit l'écriture d'une page. Elle ne se voit pas : une page obsolète ressemble en tout point à une page juste.

Pourquoi notre base de connaissance est-elle toujours obsolète ?

Parce que c'est une copie du produit faite à une date, et que le produit continue de changer. Un changement de code ne signale pas les pages qu'il rend fausses, et personne ne peut relire toutes les pages à chaque release. La discipline ralentit la dérive ; elle ne l'arrête pas.

Comment détecter la dérive documentaire ?

En partant des changements, pas des pages. Après une release, listez ce qui est arrivé sur la période, retrouvez les pages qui décrivent ces parties du produit, puis vérifiez chaque phrase factuelle contre ce que fait le code aujourd'hui. Dix pages tirées au hasard donnent un taux de dérive approximatif.

DeployIt met-il à jour ou génère-t-il notre documentation ?

Non. DeployIt ne génère ni documentation, ni changelog, ni page d'aide, et n'écrit rien dans votre base de connaissance. Il répond aux questions depuis le code, dans Claude, avec un statut sur chaque réponse ; la personne qui tient la page lit la réponse et corrige le texte.

Le wiki et le code se contredisent : lequel a raison ?

Sur ce que fait le produit (une limite, une valeur par défaut, une règle), le code, quand la réponse revient « Vérifié ». Sur la raison d'un choix ou la façon de travailler de l'équipe, le wiki : le code ne contient aucune décision. Quand ils divergent sur un comportement, soit la page est périmée, soit le code a un défaut, et c'est une personne qui tranche.

Connecter mon code