Organisation des fichiers de doc blocks dbt

dbt ne se soucie pas de l’emplacement de vos fichiers .md de doc blocks — tout fichier .md dans vos chemins de ressources est analysé. Cette flexibilité signifie que vous avez besoin d’un pattern d’organisation délibéré, sinon les doc blocks finissent éparpillés de manière à les rendre difficiles à trouver et à maintenir.

Quatre patterns existent en pratique. Chacun fait des compromis différents en termes de découvrabilité, de maintenance et de scalabilité.

Pattern 1 : fichiers par répertoire (recommandation dbt Labs)

Placer un fichier .md par répertoire, aux côtés des fichiers YAML et SQL, avec un préfixe underscore pour qu’il remonte en tête de liste :

models/marts/marketing/
├── _marketing__docs.md          # Doc blocks pour ce répertoire
├── _marketing__models.yml       # Configs, tests, descriptions de modèles
├── mrt__marketing__session.sql
└── mrt__marketing__campaign_performance.sql

Le préfixe underscore trie les fichiers de documentation au-dessus des fichiers SQL dans les listings de répertoires. Les doubles underscores séparent le nom du répertoire du type de fichier, correspondant aux conventions de nommage utilisées pour les fichiers YAML.

Points forts : Cohérent avec les conventions dbt Labs. Facile à trouver — si vous regardez le SQL d’un modèle, les doc blocks sont dans le même répertoire. Scale de manière prévisible à mesure que vous ajoutez des répertoires.

Points faibles : Les descriptions de colonnes qui s’appliquent à plusieurs répertoires (comme customer_id) n’ont pas de lieu naturel. Vous finissez par choisir un répertoire arbitraire ou dupliquer la référence du doc block.

Pattern 2 : fichiers par modèle

Donner à chaque modèle son propre fichier .md :

models/marts/marketing/
├── mrt__marketing__customer_ltv.md
├── mrt__marketing__customer_ltv.sql
├── mrt__marketing__session.md
├── mrt__marketing__session.sql
└── _marketing__models.yml

Points forts : Découvrabilité maximale — la documentation de chaque modèle est juste à côté de son SQL. Bon pour les modèles complexes avec de longs doc blocks détaillés. Pas d’ambiguïté sur l’endroit où placer un doc block de niveau modèle.

Points faibles : Crée beaucoup de fichiers. Les descriptions de colonnes partagées ont encore besoin d’un lieu. Pour les modèles simples avec des descriptions courtes, la surcharge d’un fichier séparé est difficile à justifier quand la description pourrait être inline dans le YAML.

Pattern 3 : dossier docs centralisé

Mettre tous les doc blocks dans un répertoire docs/ dédié configuré via docs-paths :

docs-paths: ["docs"]

docs/
├── shared_columns.md    # customer_id, created_at, etc.
├── marts_marketing.md   # Tous les doc blocks de marts marketing
├── marts_finance.md     # Tous les doc blocks de marts finance
└── sources.md           # Documentation des sources

Points forts : Séparation propre de la documentation du code. Les colonnes partagées ont un lieu évident. Bon pour les grands projets où les descriptions de colonnes communes ne devraient pas être rattachées à un répertoire particulier.

Points faibles : La documentation est physiquement éloignée des modèles qu’elle décrit. Les développeurs doivent naviguer vers un répertoire différent pour mettre à jour la documentation. Il est plus facile d’oublier de mettre à jour la documentation quand elle n’est pas visible aux côtés du code en cours de modification.

Pattern 4 : hybride (recommandé pour les projets en croissance)

Définir les doc blocks là où les colonnes sont introduites pour la première fois — typiquement dans les modèles base — et les référencer depuis les modèles intermédiaires et mart en aval. Les nouveaux champs dérivés obtiennent leurs propres doc blocks dans leurs répertoires respectifs.

models/
├── base/
│   ├── stripe/
│   │   ├── _stripe__docs.md      # Doc blocks pour les colonnes sources
│   │   ├── _stripe__models.yml
│   │   └── base__stripe__payment.sql
│   └── ga4/
│       ├── _ga4__docs.md          # Doc blocks pour les colonnes GA4
│       ├── _ga4__models.yml
│       └── base__ga4__event.sql
├── intermediate/
│   └── ...                         # Référence les doc blocks base
└── marts/
    └── marketing/
        ├── _marketing__docs.md    # Doc blocks pour les colonnes dérivées uniquement
        ├── _marketing__models.yml
        └── mrt__marketing__customer_ltv.sql

La logique : les colonnes provenant des systèmes sources sont documentées dans la couche base, là où elles entrent dans votre projet. Les colonnes calculées et les champs de logique métier sont documentés là où ils sont créés. Tout ce qui est en aval hérite via les références {{ doc() }}.

Points forts : Suit le lignage des données — la documentation réside là où la colonne prend son origine. Minimise la duplication. Scale bien car chaque couche ne documente que ce qu’elle ajoute.

Points faibles : Nécessite de la discipline sur la couche qui « possède » la documentation d’une colonne. Les nouveaux membres de l’équipe doivent comprendre la convention pour savoir où chercher ou ajouter des doc blocks.

Choisir un pattern

Pour la plupart des équipes, l’approche hybride fonctionne le mieux à mesure que les projets croissent. Si vous démarrez un nouveau projet ou avez moins de 30 modèles, le pattern par répertoire est plus simple et suffisant. Le pattern centralisé fonctionne si votre équipe traite la documentation comme une préoccupation distincte du développement des modèles — rare en pratique.

Quel que soit votre choix, décidez tôt. Migrer des fichiers de doc blocks entre patterns n’est pas techniquement difficile mais est fastidieux et crée des PRs bruyantes. Configurer dbt-osmosis tôt aide car il assure la cohérence YAML quel que soit l’endroit où vos doc blocks résident.