La documentation dbt est fréquemment non lue. Une enquête Informatica de 2024 a révélé que 79 % des organisations ont des pipelines de données non documentés. Sur plus de 50 000 équipes utilisant dbt chaque semaine, l’écart entre ce que le système de documentation peut produire et ce que les équipes maintiennent réellement reste large. Les problèmes sont structurels : inadéquation des audiences, limitations de l’interface, contraintes de portée, et lacunes d’application.
Inadéquation des audiences
Les ingénieurs écrivent la documentation d’un point de vue technique. Les personnes qui ont le plus besoin des définitions de données — analystes, directeurs marketing, chefs de produit — trouvent la documentation à orientation technique peu intuitive et peu utile.
Comme le souligne l’analyse 2025 de Select Star : « De nombreux collègues n’ouvrent jamais dbt Docs. Les utilisateurs non techniques veulent des ERDs, du lignage, et une recherche intégrée à l’application. Lorsque les définitions vivent uniquement en YAML, elles sont difficiles à trouver. »
Un modèle décrit comme « Joint stg_orders avec stg_customers sur customer_id et filtre pour le statut completed » indique à un ingénieur comment fonctionne le modèle mais ne dit rien à un analyste sur ce pour quoi il peut l’utiliser. Le même modèle décrit comme « Commandes e-commerce complétées avec les informations client, une ligne par commande, hors annulations » dit à l’analyste tout ce dont il a besoin pour décider si c’est la bonne table pour son analyse.
Si un projet dbt ne sert que des analytics engineers, des descriptions à orientation technique conviennent. La plupart des projets dbt servent des audiences plus larges.
Limitations de l’interface
Même lorsque les équipes rédigent des descriptions approfondies, dbt docs generate produit un site statique destiné aux ingénieurs de données. La visualisation du DAG, l’arbre des modèles, la mise en page centrée sur le SQL — tout cela suppose que le lecteur pense en termes de transformations et de lignage.
Les utilisateurs métier qui ont besoin de chercher ce que « valeur vie client » signifie dans leur organisation ne naviguent pas par DAG. Ils veulent rechercher un concept et trouver une définition claire. L’interface dbt docs par défaut ne prend pas bien en charge ce flux de travail.
Pour les utilisateurs de dbt Core, il y a un obstacle supplémentaire : l’hébergement. La commande dbt docs serve intégrée n’est explicitement pas destinée à la production. Les alternatives — GitHub Pages, S3 avec Lambda, Netlify — nécessitent un travail DevOps que la plupart des équipes de données ne peuvent pas prioriser. Le résultat est une documentation qui existe techniquement mais n’est pratiquement pas accessible aux personnes qui en ont besoin.
Pousser les descriptions vers les commentaires de l’entrepôt via persist_docs contourne entièrement ce problème. Vos descriptions apparaissent dans le panneau de schéma de BigQuery, les commentaires de colonnes Snowflake, et tout outil BI qui lit les métadonnées de l’entrepôt. Les analystes voient votre documentation sans jamais ouvrir le site docs. Si l’adoption est votre problème principal, c’est souvent la correction avec le meilleur rapport effort/impact.
Contraintes de portée
dbt Docs ne couvre que les assets gérés dans le projet dbt. Les outils BI, les tables d’entrepôt hors dbt, les sources Fivetran, les DAGs Airflow et les pipelines externes restent invisibles. Un utilisateur métier cherchant de la documentation sur les données derrière son tableau de bord Looker peut ne pas trouver ce dont il a besoin parce que la table concernée se situe en dehors des limites de dbt.
Les consommateurs de données obtiennent une image partielle qui peut ne pas inclure les tables qui les intéressent le plus. C’est une limitation fondamentale de la documentation dbt en tant que solution autonome. Les équipes dont la plateforme de données comprend plus que « dbt + un entrepôt » ont finalement besoin d’un catalogue de données qui extrait les métadonnées de tous leurs outils dans une vue unifiée.
Dérive de la maintenance
Sans application, la couverture de la documentation s’érode sprint après sprint. La propriété reste floue et les révisions sont ad hoc. Les descriptions se désynchronisent avec les modèles qu’elles décrivent — une documentation périmée induit activement en erreur.
Même lorsque les équipes rédigent initialement des descriptions adaptées aux utilisateurs métier, ces descriptions dérivent à mesure que le projet évolue. Les ingénieurs qui remarquent la dérive sont les moins susceptibles de mettre à jour des descriptions en prose pour une audience non technique.
Patterns qui améliorent l’adoption
- Écrire pour la finalité métier plutôt que la fonction technique : ce que signifient les données, pas comment elles sont construites
- Placer les descriptions où les gens travaillent déjà (commentaires d’entrepôt, intégrations avec les outils BI) plutôt que d’attendre que les gens visitent un site docs séparé
- Personnaliser le point d’entrée du site docs avec une page
__overview__qui oriente les utilisateurs non techniques - Utiliser les blocs doc avec des sections pour différentes audiences — contexte métier en haut, détails techniques en dessous
- Appliquer la documentation en CI pour que la couverture ne s’érode pas silencieusement
- Traiter la qualité de la documentation comme de l’infrastructure pour les outils d’IA qui lisent les descriptions de schémas pour générer du code