La documentation obsolète est pire que la documentation manquante. La documentation manquante est reconnaissable : un analyste qui ne voit aucune description sait qu’il doit investiguer. La documentation obsolète supprime ce signal — une colonne décrite comme “Chiffre d’affaires total net des remboursements” qui inclut maintenant la TVA (parce que le SQL a changé sans que le YAML soit mis à jour) semble faire autorité. L’analyste lui fait confiance, construit un dashboard dessus, et les chiffres sont silencieusement faux.
La trajectoire par défaut
Les projets dbt suivent un pattern commun : la documentation rédigée lors du développement initial reste figée pendant que le projet évolue — des colonnes sont ajoutées, des modèles sont refactorisés, la logique métier change. Une étude Informatica de 2024 a révélé que 79 % des organisations ont des pipelines de données non documentés. Une proportion substantielle des 21 % restants a une documentation obsolète — techniquement présente, fonctionnellement trompeuse.
Les mises à jour manuelles de la documentation ne passent pas à l’échelle : le processus n’a pas de mécanisme de feedback quand quelqu’un oublie de mettre à jour une description. L’oubli est invisible ; les conséquences sont différées.
Le modèle de dommages
La documentation obsolète cause des dommages via trois canaux :
Fausse confiance dans les analyses. Un analyste qui fait confiance à une description qui ne reflète plus la réalité produira des rapports incorrects sans le savoir. Contrairement à une erreur de requête (qui échoue bruyamment), une erreur sémantique (utiliser la mauvaise définition d’une métrique) échoue silencieusement. Le dashboard semble correct. Les chiffres sont faux.
Erreurs IA en cascade. Les outils IA lisent de plus en plus les descriptions de schéma pour générer du SQL, répondre à des questions, et construire des analyses. Quand ces descriptions sont fausses, l’IA produit confidemment du code basé sur de fausses suppositions. Les outils de documentation IA qui génèrent des descriptions lisent également les descriptions existantes comme contexte — donc les docs obsolètes ne trompent pas seulement les humains, elles entraînent l’IA à répéter les erreurs.
Érosion de la confiance dans la documentation comme système. Une fois qu’une équipe découvre que la documentation ne peut pas être fiable, elle cesse de la lire. L’investissement dans la documentation devient contre-productif : il décourage les futurs efforts de documentation tout en n’apportant aucun bénéfice.
Pourquoi la discipline manuelle seule ne suffira pas
Quand le SQL change sans mise à jour de la documentation, aucun test n’échoue, aucune vérification CI ne se déclenche (sauf si la détection de dérive est configurée), et aucun réviseur ne le remarque à moins de comparer le diff SQL avec chaque description YAML. La dérive de la documentation n’a pas l’équivalent d’un test qui échoue — pas de signal immédiat, et pas de blocage du pipeline. Le problème s’accumule silencieusement.
La réponse par l’automatisation
La solution n’est pas plus de discipline — c’est l’automatisation en couches qui détecte la dérive à plusieurs points :
- Des hooks pre-commit qui bloquent les commits sans descriptions pour les modèles modifiés
- La détection de dérive qui signale quand le SQL change sans mises à jour YAML correspondantes
- Le suivi de la couverture qui détecte l’érosion à l’échelle du projet avant qu’elle ne devienne sévère
- La remédiation IA qui génère des ébauches de descriptions pour les lacunes
Chaque couche adresse un mode d’échec différent. Ensemble, elles font de la documentation obsolète l’exception plutôt que la trajectoire par défaut. L’objectif n’est pas la perfection — c’est de réduire la fenêtre entre le moment où la documentation devient obsolète et le moment où quelqu’un le remarque.
L’exactitude importe plus que la couverture. Un projet avec 70 % de couverture où chaque description est à jour est plus utile qu’un projet avec 100 % de couverture où la moitié des descriptions ont six mois de retard.