1. Le problème de dérive documentaire
Toute équipe data l’a vécu : une nouvelle personne demande « à quoi sert cette table ? ». Vous envoyez le lien wiki. Dix minutes plus tard : « La doc dit que la colonne est obligatoire, mais 40 % des lignes sont null ». Dernière mise à jour : il y a 8 mois.
Le cercle vicieux
Docs qui dérivent → perte de confiance → on ne les consulte plus → on ne les maintient plus → elles dérivent encore plus. Il faut changer la façon de créer et de maintenir la doc, pas seulement demander « pensez à mettre à jour ».
Pourquoi la doc dérive
Docs séparées du code
La doc est dans Confluence, le schéma dans SQL. Quand vous changez le SQL, vous devez penser à la doc. Souvent, ce n’est pas fait.
Pas de validation ni d’exigence
Aucun test ne casse quand la doc est obsolète. Des PR sont mergées sans mise à jour. Personne ne le voit avant qu’une question arrive.
Les mises à jour manuelles ne passent pas à l’échelle
Avec 500+ tables et 5 déploiements par jour, impossible de tout mettre à jour à la main. Pourtant beaucoup essaient.
Incentives mal alignés
Les ingénieurs sont récompensés pour livrer vite, pas pour documenter. La doc devient « je le ferai quand j’aurai le temps » (jamais).
La solution
La seule façon de garder la doc synchronisée est de la rendre automatique. Extraire les métadonnées depuis vos systèmes, intégrer la doc au workflow de dev, rendre la staleness visible. La doc doit être un sous-produit de la construction, pas une tâche à part.
2. Le coût des documents obsolètes
Des docs périmées ne sont pas seulement agaçantes – elles coûtent cher. Voilà ce qui arrive quand la doc ne correspond plus à la réalité.
Temps gaspillé
Les ingénieurs passent des heures dans le code et Slack pour comprendre les données au lieu de construire.
Coût : 5–10 h/semaine par ingénieur dans une équipe de 10 = 50–100 h/semaine
Mauvaises hypothèses
Les analystes construisent des dashboards sur des docs périmées et tirent de mauvaises conclusions.
Coût : Mauvaises décisions, perte de confiance, rework
Onboarding lent
Les nouveaux ne font pas confiance à la doc, ils apprennent tout par Slack auprès des seniors.
Coût : 2–3 mois pour être productif au lieu de 2–3 semaines
Travail dupliqué
Des équipes reconstruisent des tables existantes parce qu’elles ne les trouvent pas ou ne les comprennent pas.
Coût : Pipelines, stockage et compute redondants
Impact terrain
Une fintech a constaté :
Après l’automatisation de la doc, l’onboarding des analystes est passé de 12 à 3 semaines. Velocity +40 %.
Une SaaS a découvert :
Trois tables « monthly revenue » donnaient des chiffres différents. Raison : docs périmées, aucune source canonique claire.
Retour d’expérience
J’ai passé 6 heures à débugger un dashboard pour découvrir que la doc disait « revenue » mais la colonne contenait « gross merchandise value ». Doc de 2019, définition changée en 2021. De bonnes docs auraient évité cette journée perdue.
3. Approche automation-first
L’idée clé : la documentation doit être extraite, pas écrite. Plutôt que de demander aux ingénieurs de tout maintenir à la main, tirez automatiquement les métadonnées des systèmes et ajoutez le contexte humain.
Le modèle de documentation en trois couches
Métadonnées auto-générées (85 %)
Extraites automatiquement depuis vos systèmes. Toujours à jour car issues de la source de vérité.
Contexte embarqué (10 %)
Écrit par les ingénieurs dans le code, extrait automatiquement au déploiement.
Annotations humaines (5 %)
Contexte à forte valeur qui ne peut pas être extrait. À ajouter avec parcimonie via l’UI du catalogue.
Comment l’automatisation marche en pratique
Découverte de schéma
Les catalogues scannent le warehouse toutes les heures pour détecter les changements de schéma. Les nouvelles colonnes apparaissent automatiquement, les supprimées sont marquées dépréciées.
Outils : Atlan, Alation, Collibra, Select Star
Suivi de lineage
Parser le SQL des pipelines pour construire le lineage. Chaque changement met le graphe à jour automatiquement.
Outils : dbt lineage, SQLLineage, DataHub, OpenLineage
Docs-as-code
Écrire les descriptions en YAML à côté du SQL. CI/CD les valide et les publie. Les docs vivent dans git, versionnées avec le code.
Outils : dbt, DataHub YAML, docs de DAG Airflow
Pro tip
Shift-left la documentation
Le meilleur moment pour documenter est quand vous codez : le contexte est frais et vous êtes déjà dans le fichier. Ajoutez la description dans le YAML dbt, un docstring dans votre transform Python. Votre futur vous (et votre équipe) vous remerciera.
4. Que faut-il automatiser ou documenter à la main
Tout ne doit pas être automatisé. Tout ne doit pas être manuel. Voici comment trancher.
Toujours automatiser
- • Schéma : noms de colonnes, types, nullabilité
- • Lineage : dépendances amont/aval
- • Usage : fréquence des requêtes, colonnes populaires
- • Fraîcheur : timestamp de dernière mise à jour
- • Volume : row counts, taille des données
- • Qualité : taux de null, unicité
- • Patterns de requêtes : joins et filtres courants
Documenter manuellement
- • Contexte métier : ce que représentent les données
- • Logique de calcul : comment les métriques sont calculées
- • Points d’attention : problèmes de qualité, edge cases
- • Ownership : qui contacter
- • SLAs : fraîcheur et qualité attendues
- • Cas d’usage : quels dashboards/reports l’utilisent
- • Historique des changements : pourquoi ce champ a été ajouté
| Type d’information | Approche | Raison |
|---|---|---|
| Schéma de table | Auto-extract | Toujours correct, pas de dérive |
| Descriptions de colonnes | Docs-as-code | Vit avec le SQL, versionné dans git |
| Data lineage | Auto-extract | SQL parsé, toujours à jour |
| Signification métier | Manuel | Nécessite du contexte humain |
| Fréquence d’usage | Auto-extract | Tiré des logs de requêtes |
| Problèmes connus | Manuel | Savoir tacite, à ajouter au fil de l’eau |
| Dernier refresh | Auto-extract | Issu des métadonnées du warehouse |
| Caveats de calcul | Docs-as-code | Écrire dans la description dbt, extraire |
Exemple : modèle dbt avec doc embarquée
# models/marts/revenue/monthly_revenue.sql
{{
config(
materialized='table',
description='Monthly revenue aggregated from orders. **Caveat**: Excludes refunds processed >30 days after order.'
)
}}
-- Column-level docs in schema.yml
version: 2
models:
- name: monthly_revenue
description: |
Monthly revenue by product category.
**Calculation**: SUM(order_total) WHERE order_status = 'completed'
**Owner**: [email protected]
**SLA**: Updates daily at 6 AM UTC
columns:
- name: month
description: Calendar month (YYYY-MM-01)
- name: category
description: Product category from dim_products
- name: revenue
description: |
Total revenue in USD.
**Note**: Does not include tax or shipping.5. Intégrer la documentation au workflow
Le secret pour garder des docs à jour : en faire une partie du process de développement, pas une étape après coup. Voici les points clés.
1. Checks dans le template de PR
Ajoutez une section doc dans votre template de PR. Les reviewers vérifient que les nouvelles tables ont une description.
Exemple de template GitHub :
## Documentation Checklist - [ ] dbt model has description - [ ] New columns have descriptions - [ ] Calculation logic is documented - [ ] Owner is specified in schema.yml - [ ] Known caveats are noted
2. Validation CI/CD
Des checks automatiques dans la pipeline garantissent que la doc respecte les standards avant le merge.
Exemple de test dbt pour modèles non documentés :
# Check that all models have descriptions
SELECT
model_name
FROM {{ ref('dbt_models') }}
WHERE description IS NULL
OR description = ''
OR description = 'TODO'
-- This test will fail if any models are undocumented3. Alertes de staleness
Rappels automatiques quand des tables très utilisées n’ont pas été revues depuis 6+ mois.
Rappel Slack hebdo :
Ces tables très utilisées n’ont pas été revues depuis 6+ mois :
•
orders_mart - last reviewed 8 months ago•
customer_ltv - last reviewed 10 months agoMerci de vérifier et mettre à jour.
4. Sprints doc trimestriels
1 jour par trimestre pour mettre à jour la documentation critique.
À revoir :
- • Top 20 tables les plus requêtées (docs toujours exactes ?)
- • Tables récemment dépréciées (bien marquées ?)
- • Dashboards prioritaires (lineage documenté ?)
- • Docs d’onboarding (reflètent-elles la réalité actuelle ?)
Pro tip
Rendre la documentation visible
Ajoutez un dashboard « Health documentation » à vos métriques d’équipe. Suivez : % de tables documentées, staleness moyenne, % de PR mergées avec doc. Ce qui est mesuré s’améliore.
6. Outils pour automatiser la documentation
La modern data stack propose d’excellents outils pour garder la doc synchronisée. Voici comment ils s’articulent.
| Outil | Ce qu’il automatise | Idéal pour | Tarification |
|---|---|---|---|
| dbt Docs | Lineage, schéma, descriptions | Couche de transformation | Gratuit (OSS) |
| Atlan | Découverte de schéma, lineage, usage | Catalogue entreprise | Enterprise |
| Select Star | Lineage, usage, popularité | Découverte basée sur l’usage | Payant |
| DataHub | Ingestion de métadonnées, lineage | Plateforme metadata OSS | Gratuit (OSS) |
| Datadef | Diagrammes visuels, lineage | Documentation visuelle | Free tier + payant |
| Alation | Catalogue complet avec enrichissement ML | Grandes entreprises | Enterprise |
Stack recommandé par taille d’équipe
Petites équipes (2–5)
- • dbt docs pour la transformation
- • README dans git pour le haut niveau
- • Datadef pour les diagrammes visuels
Priorité aux outils légers et gratuits
Mid-size (6–20)
- • dbt docs + dbt Cloud
- • DataHub ou Select Star
- • Datadef pour la doc stakeholders
Ajouter un catalogue pour la découverte
Grandes (20+)
- • Atlan ou Alation
- • Intégration dbt Cloud
- • DataHub pour le metadata custom
Catalogue enterprise avec gouvernance
Retour d’expérience
Commencez simple. Beaucoup d’équipes investissent trop tôt dans des catalogues coûteux avant d’avoir des docs-as-code fonctionnelles. Mettez d’abord en place les descriptions dbt, prouvez la valeur, puis ajoutez un catalogue si besoin. Vous pourrez toujours passer à l’enterprise plus tard.
7. Bonnes pratiques pour garder les docs synchronisées
Automatiser les parties structurelles
Schéma, lineage, stats d’usage doivent être auto-extraits. Ne demandez pas aux humains de maintenir ce que les systèmes savent.
Écrire la doc dans le code, pas dans un wiki
Utilisez YAML dbt, commentaires SQL, docstrings Python. La doc près du code reste à jour. Dans Confluence, non.
Faire de la doc une partie des revues de PR
Ajoutez des checks dans le template. Les reviewers vérifient les descriptions des nouvelles tables/colonnes.
Mettre en place des alertes de staleness
Rappels Slack automatiques quand des tables à fort usage n’ont pas été revues depuis 6+ mois.
Prioriser les tables à forte valeur
Documentez les 20 % de tables qui reçoivent 80 % des requêtes. Ne cherchez pas à tout documenter d’un coup.
Utiliser CI/CD pour faire respecter les standards
Faire échouer les builds si les modèles critiques n’ont pas de description. La bonne doc est non négociable.
Inclure l’ownership dans les métadonnées
Chaque table doit avoir un owner. Quand la doc est floue, on sait qui contacter.
Sprints doc trimestriels
1 jour par trimestre pour mettre à jour et améliorer la doc. En faire un rituel d’équipe.
Mesurer la santé de la doc
% de tables documentées, staleness, conformité PR. Ce qui est mesuré est maintenu.
Rendre la doc découvrable
Si personne ne trouve vos docs, elles n’existent pas. Intégration Slack, extensions IDE, UI de catalogue.
Anti-patterns à éviter
- • Maintenir la doc dans un wiki/Confluence séparé
- • Demander aux juniors de « tout documenter »
- • Aucune validation que la doc correspond à la réalité
- • Doc traitée après coup, pas dans les PR
- • Sur-documenter des tables triviales, sous-documenter les critiques
Règle d’or
Si ça peut être automatisé, automatisez
Les humains sont mauvais pour maintenir la doc à la main. On oublie, on est occupés, on dépriorise. L’automatisation n’oublie pas. Extrayez ce qui peut l’être, embarquez ce qui doit être dans le code et documentez manuellement le contexte à forte valeur qui ne peut pas être extrait.
8. Questions fréquentes
Pourquoi la doc data devient-elle obsolète si vite ?
La doc dérive car elle vit séparément du code. Quand les ingénieurs modifient les pipelines, ils se concentrent sur la modification, pas sur la doc. Sans automatisation ou intégration au workflow de développement, les docs deviennent périmées en semaines.
Comment automatiser les mises à jour ?
Utilisez des outils qui extraient la métadonnée directement de votre stack : dbt docs, catalogues qui scannent le warehouse, outils de lineage, intégrations CI/CD qui valident la doc à chaque PR. Objectif : la doc comme sous-produit du dev.
Que documenter automatiquement vs manuellement ?
Auto-généré : schémas, lineage, patterns de requêtes, usage, fraîcheur. Manuel : contexte métier, logique de calcul, caveats connus, problèmes de qualité, ownership. Règle : automatisez le "quoi", documentez le "pourquoi".
Comment mobiliser l’équipe ?
Faites-en une partie du workflow : checks dans les PR, rappels automatiques, reconnaissance pour les bonnes docs, et montrez la valeur via le temps de debug économisé.
Quel ROI sur l’automatisation de la doc ?
Les équipes avec doc automatisée rapportent : onboarding 40 % plus rapide, 50 % de temps de debug en moins, 30 % de tables dupliquées en moins. Payback en 2–3 mois. Le coût des mauvaises docs dépasse l’investissement.
Catalogue ou seulement dbt docs ?
Commencez par dbt docs si vous êtes <20. Ajoutez un catalogue (DataHub, Select Star, Atlan) quand vous avez 100+ tables, plusieurs outils, besoin d’analytics d’usage ou de conformité. Les catalogues apportent découverte et gouvernance ; dbt docs est idéal pour le lineage côté engineering.
Documentez visuellement votre architecture data
Créez des diagrammes clairs et toujours à jour de votre plateforme data. Montrez à votre équipe et vos parties prenantes comment les données circulent.
Guides associés
Documentation des pipelines data
Bonnes pratiques de documentation de pipelines
Guide des data contracts
Schéma, SLAs et enforcement pour des pipelines fiables
Meilleurs outils pour diagrammes d’architecture data
Comparer les outils de diagramme pour les équipes data
Bonnes pratiques de data lineage
Tracer les données de la source au dashboard