La qualité de la documentation détermine directement l’utilité des outils IA pour interroger, générer du SQL et construire sur une plateforme de données. Roche, la société pharmaceutique, a construit un chatbot sur sa documentation technique ; les ingénieurs l’ont jugé inutile. Après investigation, ils ont conclu que leur documentation « n’était pas à la hauteur ». La conclusion du responsable technique Yannick Misteli : « Si votre documentation n’est pas bonne, votre chatbot ne le sera pas non plus. »
La boucle de rétroaction
La relation entre la qualité de la documentation et l’utilité des outils IA fonctionne dans les deux sens :
Les docs alimentent l’IA. Les outils IA lisent les descriptions de schéma pour comprendre ce que représentent les tables et les colonnes. Un modèle décrit comme « Table des commandes » ne fournit rien à l’IA. Un modèle décrit comme « Commandes e-commerce complétées depuis Shopify, une ligne par commande, exclut les transactions annulées et les transactions test » donne à l’IA suffisamment de contexte pour générer des requêtes correctes, recommander la bonne table pour une question métier, et éviter de joindre au mauvais grain.
L’IA alimente les docs. Les outils de documentation par IA lisent les descriptions existantes comme contexte lors de la génération de nouvelles. Si votre modèle de base décrit customer_id de manière insuffisante, chaque description générée par IA en aval hérite de cette mauvaise définition. L’IA ne se contente pas d’échouer à améliorer une mauvaise documentation — elle la propage dans l’ensemble du projet.
Une mauvaise documentation se compose à travers les sorties IA. Lorsqu’un outil IA génère avec assurance du SQL basé sur une description qui ne reflète plus la réalité — parce que la description est devenue obsolète — la requête résultante est silencieusement incorrecte. Contrairement à une erreur de syntaxe qui échoue bruyamment, une erreur sémantique (interroger la mauvaise métrique parce que la description indiquait chiffre d’affaires net alors qu’il s’agissait en réalité du chiffre d’affaires brut) produit des résultats qui semblent plausibles. Le tableau de bord semble correct. Les chiffres sont faux.
La même description qui aide un analyste à comprendre une table aide également un assistant IA à générer du SQL correct. L’effet multiplicateur de la qualité de la documentation a augmenté avec l’adoption des outils IA.
Ce qu’apporte l’application des règles
FINN, un service mondial d’abonnement automobile, a implémenté des pre-commit hooks pour la propriété des modèles, les conventions de nommage et les exigences de description. Datafold a rapporté que FINN avait « franchi une frontière vitesse-qualité » où les vérifications automatisées ont éliminé le compromis entre la qualité des données et la vélocité des développeurs. L’application était automatique, produisant à la fois un développement plus rapide et une meilleure couverture de documentation.
Kiwi.com a associé dbt à Atlan et réduit la charge de documentation des ingénieurs de 53 % en 90 jours. L’enseignement clé : combiner la couche d’authoring de dbt avec un catalogue dédié a réduit la charge au lieu de la doubler. Les ingénieurs rédigeaient les descriptions une fois en YAML, et le catalogue rendait ces descriptions découvrables pour les utilisateurs métier et les outils IA.
L’équipe de Dmytro Arkhypov a constaté que leurs pages Confluence étaient devenues peu fiables — certains modèles documentés dans un état obsolète, d’autres bloqués en brouillon. Déplacer la documentation dans dbt a permis d’automatiser la validation. Ils ont implémenté dbt-checkpoint pour l’application et construit un générateur de documentation personnalisé qui a réduit de moitié le temps de documentation manuelle. Le passage d’un wiki à une documentation dans le code n’était pas une question de format ; il s’agissait de rendre l’automatisation possible.
La documentation qui vit près du code et est appliquée automatiquement reste précise. La documentation qui vit dans un système séparé et dépend de la discipline dérive.
Le standard de documentation prête pour l’IA
Ce qui rend la documentation « prête pour l’IA » est la même chose qui la rend utile pour les humains, avec quelques considérations supplémentaires :
- Déclarations de grain explicites. « Une ligne par client par jour » aide une IA à éviter des agrégations incorrectes. Sans cela, l’IA devine, et se trompe souvent.
- Exclusions explicites. « Exclut les transactions annulées et les transactions test » empêche une IA d’inclure des enregistrements devant être filtrés. C’est la source la plus courante d’erreurs dans le SQL généré par IA à cause d’une mauvaise documentation.
- Conventions de nommage cohérentes. Les outils IA apprennent des patterns depuis votre projet. Si certains modèles utilisent
amountpour désigner le chiffre d’affaires brut et d’autres pour le chiffre d’affaires net, l’IA n’a aucun moyen de les distinguer. - Contexte métier, pas seulement fonction technique. Les pipelines RAG et les fichiers CLAUDE.md aident à combler cet écart, mais la base reste des descriptions expliquant ce que les données signifient pour l’entreprise, pas seulement comment le SQL les transforme.
Le cadre des trois questions — système source, grain, inclusions/exclusions — produit des descriptions qui servent bien les humains et les outils IA. Les descriptions répondant à ces questions donnent à l’IA suffisamment de contexte pour générer du code utile. Les descriptions n’y répondant pas forcent l’IA à halluciner du contexte, ce qui donne des requêtes qui semblent correctes mais joignent sur la mauvaise clé ou filtrent sur le mauvais statut.
Implications pratiques
La qualité de la documentation affecte la productivité des workflows augmentés par IA dans l’ensemble de la stack de données : génération de SQL, exploration de données, tests automatisés, investigation d’anomalies. Un modèle mart où chaque description inclut le système source, le grain et les exclusions donne aux outils IA suffisamment de contexte pour générer des requêtes correctes. Un modèle décrit uniquement comme « Table des commandes » ne le fait pas.
Notes d’implémentation pertinentes : dbt Documentation CI Enforcement couvre l’application automatisée ; dbt Documentation Automation Strategy couvre les patterns de maintenance ; RAG for dbt Documentation couvre la couche de contexte métier que l’automatisation ne peut pas générer.