Stratégie d'automatisation de la documentation dbt

Ce guide couvre une approche graduée de l’automatisation de la documentation dbt. Chaque couche traite un mode de défaillance différent. Prérequis : un projet dbt fonctionnel avec un manifest.json.

Couche 1 : Prévenir les nouvelles lacunes (toute taille d’équipe)

Installer dbt-checkpoint avec check-model-has-description comme hook pre-commit. Cette seule étape empêche de nouveaux modèles non documentés d’entrer dans le projet sans toucher à la dette existante.

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

Les nouveaux modèles bénéficient d’une application des descriptions au moment du commit. Les modèles existants ne sont pas affectés. C’est l’automatisation minimale viable de la documentation — aucune infrastructure requise au-delà de la configuration du hook.

Le hook nécessite un manifest.json récent (d’où l’exécution préalable de dbt-parse), ce qui ajoute quelques secondes à chaque commit.

FINN, une entreprise mondiale d’abonnement automobile, a adopté cette approche et a rapporté que les vérifications automatisées ont éliminé le compromis entre la vélocité des développeurs et la qualité des données. Les standards de documentation ne dépendaient plus des relecteurs pour détecter manuellement chaque lacune.

Couche 2 : Mesurer et appliquer (projets en croissance)

Ajouter dbt-project-evaluator au CI. Les métriques de couverture de fct_documentation_coverage vous donnent une base de référence et montrent si vous progressez ou régressez.

vars:
  dbt_project_evaluator:
    documentation_coverage_target: 100

Commencer avec la sévérité définie sur « warn » pour ne pas bloquer les déploiements pendant que vous traitez les lacunes existantes. Cela vous donne de la visibilité sans friction. Une fois la couverture à un niveau raisonnable, passer à « error » pour empêcher la régression.

Pour un contrôle plus granulaire, ajouter dbt_meta_testing pour imposer des exigences de documentation par dossier :

models:
  your_project:
    marts:
      +required_docs: true

Cela reflète la réalité pratique que les modèles mart (que les analystes interrogent directement) nécessitent une documentation approfondie, tandis que les modèles de staging (détails d’implémentation internes) peuvent être documentés plus légèrement.

Ajouter le suivi de la couverture

Superposer le suivi de la couverture au-dessus de l’application. Enregistrer la sortie de dbt-coverage ou dbt-project-evaluator de chaque exécution CI pour pouvoir repérer les tendances. Un projet perdant 1 à 2 % de couverture par mois a un problème de processus que les vérifications individuelles des PR ne permettront pas de détecter.

Couche 3 : Traiter la dette existante (projets avec des lacunes de documentation)

Utiliser les blocs doc pour définir une fois les descriptions communes de colonnes et les référencer partout. Les 10 à 15 noms de colonnes qui apparaissent dans le plus de modèles (customer_id, created_at, order_id) représentent la majeure partie des descriptions dupliquées et incohérentes.

Combiner avec dbt-osmosis pour propager les descriptions depuis les modèles parents. Lorsque vous documentez customer_id dans votre modèle base, osmosis copie cette description dans chaque modèle en aval qui utilise la même colonne. Les équipes rapportent que cela économise 50 à 80 % du temps de documentation pour les nouveaux modèles.

# Propager les descriptions à travers le lignage et corriger les colonnes manquantes
dbt-osmosis yaml refactor

Exécuter osmosis comme hook pre-commit maintient les fichiers YAML synchronisés avec votre schéma réel à l’avenir. Cela capture le problème courant de dérive : quelqu’un ajoute une colonne, le YAML n’est pas mis à jour, la documentation diverge progressivement de la réalité.

Couche 4 : Automatisation complète (projets matures)

Ajouter la détection de dérive pour détecter la documentation qui existe mais est devenue périmée :

• dbt-osmosis yaml audit pour la dérive des colonnes à l’échelle du projet
• Comparaison de dates basée sur Git pour le SQL modifié sans mises à jour YAML
• dbt_schema_drift pour les changements de schéma de source en amont

Superposer dbt-coverage ou dbt-score dans CI pour le suivi des tendances avec une visibilité au niveau des PR. Le flag --cov-format markdown génère des tableaux de couverture que vous pouvez publier sous forme de commentaires de PR.

Envisager une génération assistée par IA pour la remédiation en masse. Un pattern pratique est un job planifié qui ouvre des PRs pour révision : l’automatisation signale les modèles avec des descriptions manquantes ou minces, génère des ébauches, et les soumet via le processus de révision normal. Aucune documentation ne fusionne sans approbation humaine, mais le relecteur commence à partir d’une ébauche plutôt que d’un champ vide.

L’IA fonctionne mieux comme accélérateur, pas comme remplacement. Les LLMs génèrent de bonnes premières ébauches pour les parties mécaniques — types de colonnes, relations de base, descriptions de lignage de données. Les humains ajoutent le contexte métier qui rend la documentation réellement utile : pourquoi cette métrique existe, quelles décisions elle pilote, et quels cas limites surveiller.

La pile complète

À maturité, les couches ressemblent à ceci :

La maintenance de la documentation devient un processus en grande partie automatisé avec des humains qui révisent et affinent plutôt qu’ils n’écrivent de zéro.

Notes sur les objectifs de couverture

100 % de couverture n’est pas toujours le bon objectif. Une documentation périmée cause plus de dommages qu’une documentation manquante, donc l’exactitude compte plus que la complétude. L’automatisation impose quels que soient les standards définis — un guide de style de documentation devrait définir ces standards avant que l’automatisation ne soit appliquée.