Métadonnées, lineage et documentation

« D'où vient ce chiffre ? » et « que se passe-t-il si je change cette colonne ? » sont les deux questions qui reviennent le plus souvent, et dont la réponse coûte des heures quand elle…

Guide≈ 8 min de lectureVérifiéLecture

Sur cette page

Pourquoi ce thème
Ce que mesure le thème
Les cinq niveaux
Jalons par niveau
Lecture détaillée par niveau
Atteinte partielle et notation
Passer au niveau suivant
Voir aussi

Niveau : 🟢→🔴 · Code thème : MET

Pourquoi ce thème#

« D'où vient ce chiffre ? » et « que se passe-t-il si je change cette colonne ? » sont les deux questions qui reviennent le plus souvent, et dont la réponse coûte des heures quand elle n'est pas outillée. Les métadonnées sont les données qui décrivent la donnée : définitions, types, propriétaire, classification, traductions. Le lineage (traçabilité, filiation) est le chemin d'un chiffre de la source au rapport, au niveau de la table ou de la colonne. La documentation est la part lisible et narrative. Sans elles, le savoir est dans la tête de l'auteur : un départ le détruit, une analyse d'impact devient une enquête, une demande de conformité (SEC) devient impossible à satisfaire. Un risque inverse existe : la documentation écrite à la main périme plus vite qu'elle ne se lit. La maturité consiste donc à rapprocher les métadonnées du code et à les extraire plutôt que les recopier.

Ce que mesure le thème#

Axe : du savoir tacite aux métadonnées actives, extraites du code et exploitées par la plateforme.
Indicateur clé : part des objets critiques décrits, avec un lineage à jour, et délai pour répondre à « d'où vient ce chiffre / qui est impacté ? ».
Unité : % d'objets documentés ; âge moyen de la documentation par rapport au code ; temps de réponse à une analyse d'impact (minutes, heures ou jours).

Les cinq niveaux#

Niveau	Nom court	Promesse	Indicateur type (ordre de grandeur)
1	Tacite	Le savoir est dans la tête de l'auteur ; une question demande de le trouver.	Analyse d'impact : jours
2	Écrit	Les objets principaux ont une description lisible et un schéma de l'ensemble existe.	≥ 50 % des objets critiques décrits
3	Référencé	Un dictionnaire de données et un lineage de référence existent pour les produits critiques, tenus avec les changements.	≥ 80 % décrits ; impact en heures
4	Extrait	Les métadonnées et le lineage sont extraits automatiquement du code et de la base, donc toujours à jour.	Écart doc/code ≈ 0 ; impact en minutes
5	Actif	Les métadonnées pilotent la plateforme : génération de documentation, traductions, contrôles, droits, détection d'impact avant déploiement.	Impact calculé avant toute livraison

Jalons par niveau#

ID	Jalon	Preuve vérifiable
PD-MET-1.1	Les objets du datamart ont des noms compréhensibles par un métier.	Revue d'un échantillon de dix objets par un référent métier.
PD-MET-1.2	Un schéma d'ensemble (flux sources → datamart → rapports) existe.	Diagramme daté.
PD-MET-1.3	Les scripts portent un en-tête : objet, auteur, rôle.	Échantillon de scripts avec en-tête.
PD-MET-1.4	La liste des rapports publiés et leurs propriétaires est tenue.	Inventaire des rapports.
PD-MET-2.1	Les tables critiques ont une description (rôle, grain, source).	Description sur ≥ 50 % des tables critiques.
PD-MET-2.2	Les colonnes critiques ont un libellé et une définition.	Dictionnaire partiel mais utilisable.
PD-MET-2.3	Le sens des indicateurs est écrit et accessible aux utilisateurs (ADO).	Glossaire consultable depuis le rapport.
PD-MET-2.4	Un nouvel arrivant retrouve seul la source d'un indicateur simple en moins d'une journée.	Test avec un arrivant ou une personne extérieure.
PD-MET-3.1	Un dictionnaire de données complet couvre tables, colonnes, types, règles, propriétaire.	Dictionnaire couvrant ≥ 80 % des produits critiques.
PD-MET-3.2	Un lineage de niveau table ou colonne existe pour les indicateurs critiques.	Fiche de lineage pour dix indicateurs.
PD-MET-3.3	La documentation est mise à jour à chaque changement (critère de fin d'une tâche).	Règle de livraison appliquée sur un échantillon de dix changements.
PD-MET-3.4	Les métadonnées multilingues (libellés, descriptions) sont gérées en un lieu unique.	Source unique des traductions (BI — accessibilité et multilingue).
PD-MET-4.1	Les métadonnées sont stockées avec le code (propriétés étendues, fichiers versionnés) et déployées avec lui.	Métadonnées dans le dépôt ; déploiement sans saisie manuelle.
PD-MET-4.2	Le lineage est extrait automatiquement (analyse des dépendances, modèle sémantique, pipelines).	Génération reproductible ; comparaison avec la réalité sans écart.
PD-MET-4.3	Une analyse d'impact répond en minutes (« qui consomme cette colonne ? »).	Chronométrage sur trois cas.
PD-MET-4.4	Un contrôle automatique signale les objets sans description ou sans propriétaire (GOV).	Rapport de couverture automatisé.
PD-MET-5.1	La documentation est générée depuis les métadonnées (site, dictionnaire, schémas).	Génération planifiée ; publication à chaque version.
PD-MET-5.2	L'impact est calculé avant le déploiement et bloque les changements cassants non annoncés (CTR).	Étape de pipeline d'analyse d'impact.
PD-MET-5.3	Un catalogue unique relie métadonnées techniques, métier, qualité, classification et usage.	Catalogue interrogé quotidiennement par plusieurs profils.
PD-MET-5.4	La qualité des métadonnées est elle-même mesurée et améliorée.	Indicateurs de complétude et d'exactitude suivis.

Lecture détaillée par niveau#

🟢 Niveau 1 — Tacite#

Signes : « demande à Marie » ; l'analyse d'impact se fait en ouvrant tous les rapports ; la documentation est un mail ancien.
Gain : zéro effort de rédaction.
Ne garantit pas : la continuité au départ de l'auteur.
Difficulté : 1/5 · Effort : 1/5.

🟢 Niveau 2 — Écrit#

Signes : descriptions sur les tables principales ; schéma d'ensemble ; glossaire dans le rapport.
Gain : un arrivant s'oriente seul sur les cas simples.
Ne garantit pas : l'exactitude dans le temps (la doc manuelle périme).
Difficulté : 2/5 · Effort : 2/5.

🟡 Niveau 3 — Référencé#

Signes : dictionnaire complet ; lineage pour les indicateurs critiques ; mise à jour exigée à chaque changement.
Gain : une analyse d'impact en heures ; des réponses d'audit possibles.
Ne garantit pas : l'absence de dérive (la discipline manuelle s'érode).
Difficulté : 3/5 · Effort : 3/5.

🧪 Exemple

« Peut-on renommer la colonne PRD_PILIER ? » Au niveau 1 : on cherche dans 25 rapports, une demi-journée, avec un risque d'oubli. Au niveau 4 : une requête sur les dépendances extraites (vue système de dépendances de la base, modèle sémantique et définitions de rapports) liste les consommateurs en deux minutes : trois vues, deux mesures, quatre rapports. Le renommage devient une décision, pas une enquête (voir aussi le principe expand/contract en MOD).

🟡 Niveau 4 — Extrait#

Signes : métadonnées dans des propriétés étendues ou fichiers versionnés ; lineage généré ; analyse d'impact interrogée en minutes ; contrôle de couverture automatique.
Gain : la documentation ne peut plus périmer plus vite que le code.
Ne garantit pas : le sens : un lineage parfait d'un indicateur mal défini ne dit pas ce qu'il signifie.
Difficulté : 4/5 · Effort : 4/5.

-- Analyse d'impact au niveau base : qui dépend de la colonne ? (T-SQL, dépendances référencées)
SELECT DISTINCT OBJECT_SCHEMA_NAME(d.referencing_id) AS SchemaConsommateur,
       OBJECT_NAME(d.referencing_id)               AS Consommateur,
       o.type_desc
FROM   sys.sql_expression_dependencies AS d
JOIN   sys.objects                     AS o ON o.object_id = d.referencing_id
WHERE  d.referenced_id = OBJECT_ID('[dim].[Produit]')
  AND  d.referenced_minor_id = COLUMNPROPERTY(OBJECT_ID('[dim].[Produit]'), 'PRD_PILIER', 'ColumnId');
-- Limite : le niveau colonne n'est suivi que pour les objets liés au schéma (sys.dm_sql_referenced_entities pour les autres) ; les dépendances dynamiques (SQL construit en chaîne) et les rapports ne sont pas vus.

🔴 Niveau 5 — Actif#

Signes : documentation et traductions générées ; analyse d'impact calculée avant livraison ; catalogue unifié ; qualité des métadonnées mesurée.
Gain : la plateforme se documente et se contrôle elle-même.
Ne garantit pas : l'adoption par les utilisateurs (une doc exhaustive que personne ne lit) ; revoyez ADO.
Difficulté : 5/5 · Effort : 5/5.

Atteinte partielle et notation#

Évaluez sur dix objets critiques tirés au hasard (tables, indicateurs, rapports). Un jalon de couverture vaut 1 si ≥ 9 objets sur 10 le satisfont, 0,5 si 5 à 8, 0 sinon. Les jalons « en minutes » se chronomètrent.

Un « 5 partiel » : la documentation du datamart est générée à chaque version (5.1 à 1), l'analyse d'impact manque encore les rapports (5.2 à 0,5), il n'y a pas de catalogue unifié (5.3 à 0), la qualité des métadonnées n'est pas suivie (5.4 à 0).

⚠️ Piège

La documentation à la main qui périme : un document de 200 pages dont personne ne sait ce qui est encore vrai. Symptôme : la doc dit une chose, le code une autre. Remède : tout ce qui peut être extrait l'est ; la doc manuelle ne garde que ce que le code ne dit pas (le pourquoi, les décisions, le contexte).

⚠️ Piège

Le lineage partiel qui rassure : un lineage qui ignore le SQL dynamique, les extractions manuelles et les rapports donne une fausse sécurité à l'analyse d'impact. Remède : dites ce que le lineage ne couvre pas, et complétez par un test de non-régression (REC).

💡 Astuce d'expert

Mettez la métadonnée là où le développeur travaille : propriétés étendues SQL, fichiers de définition du modèle sémantique versionnés, annotations dans le dépôt. Une métadonnée éloignée du code se renseigne une fois, puis jamais.

Passer au niveau suivant#

Moyens possibles (facultatifs)

Passage	Leviers possibles
1 → 2	Décrire d'abord les 20 tables et les 20 indicateurs les plus consommés ; ajouter un en-tête de script.
2 → 3	Faire de la mise à jour de la doc un critère de fin de tâche (définition de « terminé » — voir Scrum en pratique) ; dresser le lineage des indicateurs critiques.
3 → 4	Stocker les métadonnées avec le code ; extraire les dépendances ; contrôler la couverture dans le pipeline (DOP).
4 → 5	Générer la documentation et les traductions ; intégrer l'analyse d'impact au pipeline ; adopter un catalogue (état des offres 2026-10 à vérifier).

Pièges transverses : (1) Faux positif — une couverture de 100 % avec des descriptions du type « Colonne client » ; vérifiez la qualité du texte sur un échantillon. (2) Goodhart — viser un taux de colonnes décrites produit des descriptions vides de sens. (3) Outil sans pratique — installer un catalogue sans propriétaire de contenu aboutit à un catalogue vide.

🤖 IA

Elle excelle à proposer des descriptions de colonnes depuis leur nom et leur contenu, à résumer un lineage, à traduire des libellés, à répondre à « d'où vient ce chiffre » sur un catalogue. Risque : des descriptions plausibles mais fausses, qui acquièrent une autorité écrite. Toute description générée est marquée comme telle et validée par le propriétaire (GOV).

Voir aussi#

Même matrice : 02 Gouvernance · 04 Contrats · 05 Modélisation · 08 Sécurité · README
Autres matrices : DL — documentation et transmission du savoir · BI — gouvernance, catalogue et self-service · BI — accessibilité et multilingue · BI — modèle sémantique
Pratique : méthodes spécifiques data · CI/CD pour la data · SQL Server SaaS — vue d'ensemble · IA et reporting OneLake
Glossaire · Notation

✻ Rédigé par Claude Sonnet 5.5