Stratégie de déploiement des standards de documentation dbt

Un déploiement semaine par semaine des standards de documentation dbt : application progressive sur deux à trois mois, en commençant par les descriptions de modèles et en ajoutant des couches à mesure que chacune s’ancre. Un sprint en une fois — documenter l’ensemble d’un projet d’un coup — tend à revenir à la normale en quelques mois parce qu’aucune application n’a été établie.

Semaine 1 : Descriptions de modèles uniquement

Rédiger un guide de style d’une page couvrant uniquement les descriptions de modèles. Ne pas toucher aux descriptions de colonnes pour l’instant. Définir ce que sont les quatre questions — finalité métier, grain, exclusions, source — et partager deux ou trois exemples montrant à quoi ressemble le template en pratique :

# Template
- name: mrt__<domaine>__<concept>
  description: >
    [Quel concept métier ceci représente, en termes métier].
    Une ligne par [grain]. Exclut [tout filtre ou règle métier].
    Sources : [systèmes sources et modèles en amont].

# Exemple
- name: mrt__marketing__customer_ltv
  description: >
    Valeur vie client calculée 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.

Garder le guide de style suffisamment court pour être lu en cinq minutes. Le placer dans CONTRIBUTING.md ou dbt-styleguide.md à la racine du projet. Sur dbt Cloud, utiliser dbt-styleguide.md — le Copilot le lit automatiquement lors de la génération de documentation.

Ne pas ajouter d’application pour l’instant. Cette semaine est consacrée à établir un vocabulaire partagé et à donner à l’équipe des exemples sur lesquels s’appuyer.

Semaine 2 : Application pre-commit pour les descriptions de modèles

Ajouter check-model-has-description de dbt-checkpoint comme hook pre-commit :

repos:
  - repo: https://github.com/dbt-checkpoint/dbt-checkpoint
    rev: v2.0.6
    hooks:
      - id: check-model-has-description

Cela signifie que chaque commit qui ajoute ou modifie un modèle doit inclure une description de modèle. Les développeurs qui n’en ont pas ajouté reçoivent un échec immédiat avant que le commit ne soit enregistré, pas vingt minutes plus tard en CI.

Simultanément, exécuter dbt-codegen pour générer des stubs YAML pour les modèles existants qui n’ont pas de descriptions :

dbt run-operation generate_model_yaml --args '{"model_names": ["model_name"], "upstream_descriptions": true}'

Le flag upstream_descriptions: true extrait les descriptions des modèles parents, de sorte que vous n’avez besoin d’écrire que des descriptions genuinement nouvelles. Pour les modèles qui héritent toutes leurs colonnes d’une seule source en amont, cela peut auto-peupler une grande partie du YAML. Combler les lacunes au cours des deux ou trois sprints suivants — ne pas tout faire d’un coup.

Mois 2 : Descriptions de colonnes pour les modèles mart

Étendre les exigences aux descriptions de colonnes, mais uniquement pour les modèles mart. Pas encore pour les modèles base ou intermédiaires — cela viendra plus tard si vous le souhaitez.

Mettre à jour la configuration pre-commit pour ajouter une application graduée avec le regex files: :

hooks:
  - id: check-model-has-description
  - id: check-model-has-all-columns
    files: ^models/marts
  - id: check-model-columns-have-desc
    files: ^models/marts
  - id: check-column-desc-are-same

Le regex files: limite check-model-columns-have-desc au répertoire models/marts uniquement. Cela signifie que les modèles base et intermédiaires peuvent encore être commités sans descriptions de colonnes, tandis que les modèles mart — ceux que les utilisateurs métier interrogent réellement — nécessitent une documentation complète des colonnes.

Le hook check-column-desc-are-same capture une incohérence subtile : la même colonne décrite différemment dans deux modèles mart. Cela vaut la peine d’être appliqué à l’échelle du projet, pas seulement pour les marts — cela empêche la situation où customer_id a cinq descriptions légèrement différentes dans votre projet.

Mettre à jour votre guide de style pour inclure les patterns de description de colonnes : préciser les unités pour les colonnes numériques, inclure le fuseau horaire pour les timestamps, indiquer les relations clés pour les colonnes d’ID, énumérer les valeurs valides pour les champs de statut.

En continu : Couverture assistée par IA et suivi

Une fois que l’application fonctionne pour les descriptions de modèles mart et les colonnes, les lacunes de couverture restantes sont mieux comblées avec une assistance IA plutôt qu’un effort manuel. Utiliser dbt Copilot, Claude Code avec le serveur MCP dbt, ou Altimate AI pour générer des premières ébauches, puis affiner avec la connaissance humaine pour les modèles où le contexte métier est le plus important.

Suivre la couverture avec dbt-coverage ou dbt-project-evaluator et afficher les chiffres dans les commentaires de PR :

dbt-coverage compute doc \
  --manifest target/manifest.json \
  --catalog target/catalog.json

Les chiffres de couverture dans les commentaires de PR rendent l’état de la documentation visible lors de la révision. La tendance compte plus que le chiffre absolu — une couverture passant de 65 % à 70 % à 75 % indique un processus qui fonctionne ; une couverture bloquée à 65 % pendant trois mois indique une lacune de processus.

Ce qu’il ne faut pas faire

Quelques antipatterns de déploiement à éviter :

Ne pas exiger 100 % dès le premier jour. Commencer à un seuil que vous ne pouvez pas atteindre actuellement crée soit une crise de conformité, soit un standard que tout le monde ignore. Commencer à quel que soit votre couverture actuelle (même 30 %), faire fonctionner l’application, puis augmenter progressivement.

Ne pas imposer les descriptions de colonnes partout. Les colonnes de modèles base qui correspondent directement aux champs sources n’ont généralement pas besoin de descriptions — le nom de la colonne est la description. Réserver l’effort pour les modèles mart où les utilisateurs métier consultent la documentation.

Ne pas laisser l’application glisser « juste cette fois ». Le flag --no-verify sur les commits git est un piège. Chaque exception normalise le fait de sauter la documentation. La discipline se renforce dans les deux sens : l’appliquer de manière cohérente en fait une habitude ; la sauter une fois la rend optionnelle.

Ne pas traiter le guide de style comme permanent. Vos standards évolueront à mesure que vous apprendrez ce qui est utile et ce qui est superflu. Mettre à jour le guide de style lorsque l’équipe découvre un meilleur pattern. L’important est que le guide de style reflète la pratique actuelle, pas une pratique aspirationnelle que personne ne suit réellement.

Calendrier réaliste

Le processus complet prend environ deux à trois mois pour s’ancrer. Après cela, le CI capture les violations, les tendances de couverture restent visibles, et le guide de style fonctionne comme une convention de projet aux côtés des standards de nommage et de test.