Le problème principal avec la documentation dbt dans la plupart des projets est l’incohérence, pas l’effort. Les équipes rédigent des descriptions à différents niveaux de détail, pour des audiences imaginées différentes, sans standard partagé. Un guide de style résout le problème de cohérence : ce qu’une description doit contenir, quelle longueur elle doit avoir, et ce qui appartient à description plutôt qu’à meta.
L’incohérence sans standard
Comparez ces deux descriptions du même modèle :
# Rédigé sans guide de style- name: mrt__marketing__customer_ltv description: "Table LTV client"
# Rédigé avec un guide de style- name: mrt__marketing__customer_ltv description: > Calculs de valeur vie client avec une fenêtre glissante de 3 ans et une méthodologie de flux de trésorerie actualisé (taux d'actualisation annuel de 10 %). Une ligne par client. Exclut les clients sans commandes complétées. Sources : commandes Shopify via base__shopify__orders et paiements Stripe via base__stripe__payments.La première description ne transmet rien au-delà du nom du modèle. La seconde indique à un analyste si ce modèle répond à sa question, sans lire le SQL. Les deux auteurs ont fourni des efforts ; seul l’un avait un template définissant ce qu’il fallait inclure.
Une fois qu’une description de modèle doit répondre à quatre questions — concept métier, grain, exclusions, sources de données — les critères de révision deviennent concrets. Une description manquant le grain échoue à la révision sur un motif spécifique et articulable. La rédaction guidée par un template est également plus rapide : répondre à « quel est le grain ? » prend quelques secondes ; répondre à « écrire une bonne description » non.
Les guides de style comme pilotage de l’IA
Une deuxième fonction des guides de style, pertinente depuis 2024-2025 : les outils d’IA.
Le Copilot de dbt Cloud, dbt-osmosis, et les pipelines LLM personnalisés génèrent tous de la documentation. Sans guide de style, ils produisent une sortie générique — des noms de colonnes reformulés en phrases, des transformations SQL décrites mécaniquement — qui manque ce dont l’équipe a besoin. Un guide de style donne à l’IA un template à remplir plutôt qu’un prompt ouvert.
dbt Cloud va plus loin. Il prend en charge un fichier dbt-styleguide.md à la racine de votre projet que le Copilot lit comme contexte lors de la génération de documentation. Le guide de style que vous rédigez pour les ingénieurs humains sert doublement d’instructions pour la génération IA. Vos conventions se propagent automatiquement : si vous précisez que les descriptions de modèles doivent inclure le grain avec le pattern « une ligne par », le Copilot inclura ce pattern.
Un guide de style bien structuré agit comme un system prompt pour la génération IA, orientant la sortie vers les patterns spécifiques au projet. Le même document sert les ingénieurs humains (révisions plus rapides, onboarding cohérent) et les outils d’IA (contexte de génération structuré).
Ce qui appartient à un guide de style
Un guide de style utile pour la documentation dbt n’a pas besoin d’être long. Il doit être suffisamment court pour qu’un nouveau membre de l’équipe puisse le lire en cinq minutes. Ce qu’il doit couvrir :
Descriptions de modèles : Quelles quatre questions chaque description de modèle doit-elle répondre ? Quelle est la longueur attendue ? Comment traiter les modèles qui servent plusieurs audiences ?
Descriptions de colonnes : Quand les descriptions de colonnes sont-elles obligatoires (modèles mart, clés primaires/étrangères) versus optionnelles (colonnes de staging qui correspondent directement aux champs sources) ? Quelle information est obligatoire pour les colonnes numériques (unités, devise) ? Pour les timestamps (fuseau horaire) ?
Description vs meta : Qu’est-ce qui appartient à description (prose lisible par l’humain) versus meta (paires clé-valeur structurées pour les outils) ? La propriété, les flags PII, et les SLAs dans meta ; la finalité métier, le grain et les exclusions dans description.
Formatage YAML : Quel style de scalaire utiliser dans quelle situation. Un style maison cohérent (par exemple, scalaires pliés pour les descriptions de modèles, inline pour les descriptions courtes de colonnes) évite les débats de formatage.
Blocs doc : Quand créer un bloc doc plutôt qu’écrire inline. La convention de nommage que votre projet utilise.
Le guide de style lui-même doit résider dans votre dépôt de projet dbt — un CONTRIBUTING.md ou un dbt-styleguide.md à la racine. Ce dernier a l’avantage d’être lu automatiquement par le Copilot de dbt Cloud. Dans les deux cas, il appartient au contrôle de version aux côtés du code qu’il régit.
Application
Un guide de style nécessite deux choses pour s’ancrer : des exemples et de l’automatisation.
Des exemples — des comparaisons avant/après montrant à quoi ressemble le template en pratique — sont plus efficaces que des orientations abstraites. Deux ou trois descriptions de modèles annotées enseignent le pattern plus vite que des paragraphes d’explication.
L’automatisation transforme le standard en exigence. Les outils d’application en CI, notamment les hooks pre-commit de dbt-checkpoint, bloquent les commits qui violent le standard. La séquence de déploiement est importante : tout appliquer en même temps crée de la résistance ; commencer uniquement par les descriptions de modèles, puis étendre aux descriptions de colonnes pour les modèles mart, est un rythme que la plupart des équipes maintiennent.