Décisions d'architecture des données : comment les documenter pour qu'elles survivent aux équipes ?

Une décision d'architecture des données se documente dans une fiche courte qui précise le contexte, les options étudiées, le choix retenu, ses conséquences et les conditions de sa révision. Ces fiches se conservent dans un registre unique, relié aux composants concernés, et se remplacent au lieu de se réécrire quand une décision change.

Dans une équipe data, chaque semaine apporte son lot de décisions. Choisir un mode de traitement pour un nouveau flux, retenir un format de stockage, confier une transformation à une équipe plutôt qu'à une autre. Sur le moment, la raison de chaque choix paraît évidente à tous les participants.

Deux ans plus tard, l'équipe a changé. Un nouvel arrivant découvre un traitement quotidien là où il attendait du temps réel, une duplication de données qui lui semble inutile, un outil qu'il aurait écarté. Personne ne sait plus pourquoi ces choix ont été faits. Faute de réponse, il les remet en cause, parfois à juste titre, souvent en recréant un problème que la décision initiale avait réglé.

Une architecture dont les décisions ne sont pas documentées dépend de la mémoire de quelques personnes, et se fragilise à chaque départ. Le schéma d'architecture montre ce qui existe. Il ne dit jamais pourquoi cela existe sous cette forme.

Documenter les décisions n'exige ni outil sophistiqué ni processus lourd. Cela suppose de savoir quelles décisions méritent d'être écrites, avec quel contenu, et de faire vivre le registre dans la durée.

Pourquoi les décisions d'architecture des données se perdent

La perte des décisions d'architecture n'a rien d'une négligence individuelle. Elle découle de la manière dont ces décisions sont prises dans la plupart des organisations.

Des décisions prises en réunion, jamais écrites

Une décision d'architecture se prend rarement dans un document. Elle émerge d'une réunion technique, d'un échange entre deux personnes, d'un test concluant mené un vendredi après-midi. Le compte rendu, quand il existe, mentionne le résultat sans les raisons.

Les options écartées disparaissent encore plus vite. Or ce sont souvent elles qui protègent l'organisation contre une mauvaise décision future : savoir qu'une solution a été testée et abandonnée, avec ses raisons, évite de la retenter sur la même hypothèse erronée.

Ce que coûte une décision dont on a oublié la raison

Une décision non documentée produit des coûts qui ne se voient pas immédiatement. Ils apparaissent au fil des mois, sous plusieurs formes :

• Des débats rouverts sans fin : chaque nouvel arrivant reprend la discussion depuis le début, faute de pouvoir consulter l'argumentation initiale.
• Des décisions défaites sans le savoir : une évolution supprime une contrainte qui existait pour une bonne raison, et le problème qu'elle évitait réapparaît.
• Une dépendance aux personnes : seules une ou deux personnes peuvent expliquer l'architecture, et leur départ crée un risque majeur.
• Des révisions impossibles : sans connaître les hypothèses d'une décision, personne ne peut dire si elles ont changé et si la décision doit être revue.

Ce dernier point est central. Faire des choix d'architecture qui tiennent dans le temps suppose de pouvoir les réexaminer quand le contexte évolue. Une décision dont on ignore les hypothèses ne peut être ni défendue ni révisée.

Un schéma d'architecture ne remplace pas une décision documentée

Beaucoup d'équipes considèrent que leur architecture est documentée parce qu'elles disposent d'un schéma à jour et d'une description de chaque flux. Cette documentation est utile, mais elle répond à une autre question : elle décrit ce qui existe, pas pourquoi cela existe.

Un schéma montre qu'un flux passe par une zone intermédiaire avant d'atteindre l'entrepôt. Il ne dit pas que cette zone a été introduite pour isoler une source instable, ni que sa suppression ferait réapparaître des erreurs de chargement. La description de l'architecture et la trace des décisions sont deux documentations complémentaires, et l'une ne dispense pas de l'autre.

Les deux gagnent à se répondre. La description d'un composant renvoie vers les décisions qui l'ont façonné, et chaque décision renvoie vers les composants qu'elle concerne.

Quelles décisions d'architecture des données faut-il documenter ?

Tout documenter conduit à ne rien relire. Un registre utile se concentre sur les décisions qui engagent l'architecture dans la durée, et laisse de côté les choix courants.

Le critère : une décision coûteuse à défaire

Une décision mérite une fiche quand elle serait coûteuse à défaire, quand elle a fait l'objet d'un débat entre plusieurs options ou quand elle contraint d'autres choix à venir. Ce triple critère couvre l'essentiel des décisions structurantes.

Quelques exemples de décisions qui entrent dans ce périmètre :

• Le modèle de stockage principal : entrepôt, lac ou lakehouse, et la répartition des données entre ces espaces.
• Le mode de traitement d'un flux important : le choix entre temps réel, quasi temps réel et batch engage les coûts et la complexité pour longtemps.
• La répartition des responsabilités : le choix de centraliser ou de distribuer les données entre une équipe centrale et les domaines métier.
• Les conventions structurantes : le découpage en couches, les règles de nommage, la politique de conservation de l'historique.
• L'abandon d'une option : la décision de ne pas retenir une technologie ou une approche, avec ses raisons.

Ce qui ne mérite pas une fiche de décision

À l'inverse, certains choix ne justifient pas de documentation dédiée. Les décisions facilement réversibles, les choix d'implémentation sans impact sur le reste de l'architecture et les réglages de configuration relèvent de la documentation technique courante.

La frontière n'est pas toujours nette. En cas de doute, une question simple aide à trancher : un nouvel arrivant aurait-il besoin de connaître la raison de ce choix pour éviter de le défaire par erreur ? Si la réponse est oui, la fiche est justifiée.

Documenter les décisions déjà prises : par où commencer ?

Une organisation qui lance un registre ne part jamais de zéro. L'architecture existante repose sur des dizaines de décisions passées, dont la plupart n'ont jamais été écrites. Tenter de toutes les reconstituer décourage l'équipe avant même que la pratique ne s'installe.

Une approche plus réaliste consiste à commencer par les décisions qui posent le plus de questions aujourd'hui. Celles que les nouveaux arrivants interrogent systématiquement, celles qui reviennent dans les débats, celles qui concernent les composants les plus critiques. Une dizaine de fiches rétrospectives suffit souvent à couvrir l'essentiel.

Ces fiches rétrospectives obéissent aux mêmes règles que les autres, avec une précaution : quand la raison d'une décision passée n'est plus connue, la fiche doit le dire plutôt que de reconstruire une justification plausible. Une raison inventée après coup induit en erreur les lecteurs futurs bien plus qu'une mention honnête d'incertitude.

Le contenu d'une fiche de décision d'architecture des données

Une fiche de décision se lit en quelques minutes. Sa valeur tient moins à sa longueur qu'à la présence de quelques rubriques, toujours les mêmes, qui permettent de comprendre le choix sans avoir participé à la discussion.

Les rubriques indispensables d'une fiche de décision

Une fiche complète comporte sept rubriques. Les trois dernières sont les plus souvent oubliées, alors que ce sont elles qui rendent la décision révisable :

• Le titre et le statut : une formulation courte de la décision et son état (proposée, acceptée, remplacée).
• Le contexte : le problème à résoudre, les usages concernés et les contraintes du moment.
• Les options étudiées : au moins deux options, avec leurs avantages et leurs inconvénients.
• La décision : l'option retenue, formulée sans ambiguïté.
• Les conséquences : ce que la décision rend possible, ce qu'elle empêche et ce qu'elle coûte.
• Les conditions de révision : les changements de contexte qui justifieraient de revoir la décision.
• La date et les décideurs : qui a pris la décision, qui a été consulté, à quelle date.

Écrire court pour être relu

Une fiche de décision de dix pages ne sera pas relue. La bonne longueur tient sur un écran : quelques lignes de contexte, une liste d'options avec leurs arguments principaux, une phrase de décision, quelques conséquences.

La précision compte davantage que la longueur. « Choix d'un traitement quotidien pour limiter les coûts » reste vague. « Traitement quotidien retenu, car aucun usage identifié n'exige une fraîcheur inférieure à vingt-quatre heures » permet à un lecteur futur de vérifier si cette hypothèse tient toujours.

Les erreurs de rédaction qui rendent une fiche inutile

Une fiche peut exister et ne servir à rien. Certaines erreurs de rédaction reviennent souvent et vident la fiche de son intérêt pour le lecteur futur :

• Une seule option présentée : sans alternative documentée, la fiche ressemble à une justification après coup et ne dit rien des choix écartés.
• Un contexte implicite : la fiche suppose que le lecteur connaît la situation de l'époque, ce qui ne sera plus le cas dans deux ans.
• Des conséquences uniquement positives : toute décision a un coût ou une limite, et les taire empêche de les surveiller.
• Aucune condition de révision : la décision paraît définitive, alors qu'elle repose sur des hypothèses qui évolueront.
• Un vocabulaire réservé aux initiés : des abréviations internes et des noms de projets que personne ne comprendra hors de l'équipe.

Une relecture par une personne extérieure à la décision permet de repérer la plupart de ces défauts. Si elle comprend le choix sans poser de question, la fiche est prête.

Où et comment conserver les décisions d'architecture

Une fiche bien rédigée perd toute utilité si personne ne la trouve. Le choix de l'emplacement et des règles de conservation compte autant que le contenu.

Un emplacement unique, proche du travail des équipes

Les décisions dispersées entre une messagerie, un espace documentaire et des comptes rendus de réunion ne forment pas un registre. Elles doivent être réunies dans un emplacement unique, connu de tous et accessible sans demande particulière.

Le meilleur emplacement est celui que l'équipe consulte déjà. Pour une équipe qui travaille sur un dépôt de code, les fiches peuvent y être versionnées au même titre que les transformations. Pour une organisation plus large, un espace documentaire partagé convient, à condition qu'il ait un responsable et une structure stable.

Relier les décisions aux composants et aux métadonnées

Une décision prend tout son sens quand elle est reliée aux composants qu'elle concerne. Un lecteur qui découvre un flux doit pouvoir retrouver la fiche qui explique sa conception, et un lecteur qui consulte une fiche doit pouvoir identifier les composants touchés.

Ce lien s'appuie naturellement sur la gestion des métadonnées. Quand l'organisation dispose d'un catalogue, référencer les fiches de décision dans la description des composants concernés rend les raisons visibles là où les équipes en ont besoin. Les principes de mise en place d'un Data Catalog dès le début d'un projet s'appliquent ici directement.

Remplacer une décision au lieu de la réécrire

Une décision acceptée ne se modifie plus. Quand le contexte change et qu'une nouvelle décision s'impose, une nouvelle fiche est rédigée. L'ancienne passe au statut « remplacée » et renvoie vers la nouvelle.

Cette règle paraît contraignante. Elle préserve pourtant l'historique du raisonnement, ce qui est précisément l'objet du registre. Réécrire une fiche efface la trace de ce que l'on savait au moment de la décision, et donc la possibilité de comprendre pourquoi elle a été prise.

Rendre le registre consultable au-delà de l'équipe technique

Le registre des décisions n'est pas réservé aux ingénieurs. Les responsables métier, la direction data et les équipes chargées de la conformité ont, eux aussi, besoin de comprendre pourquoi l'architecture a pris telle forme.

Rendre le registre consultable par ces publics suppose quelques efforts de rédaction : un titre compréhensible sans connaissance technique, un contexte qui mentionne les usages concernés, des conséquences exprimées aussi en termes métier. Ces efforts profitent à tous les lecteurs, y compris techniques.

Un registre lisible par les métiers devient aussi un outil de dialogue. Une direction qui conteste un choix peut lire ses raisons et argumenter sur des faits, plutôt que de rouvrir le débat sans connaître ce qui a été étudié.

Qui décide, qui écrit, qui valide les décisions d'architecture ?

Documenter une décision suppose de savoir qui l'a prise. Dans beaucoup d'équipes, cette question reste floue, et le flou se retrouve dans les fiches.

Une répartition des rôles explicite

La répartition des rôles autour d'une décision d'architecture n'a pas besoin d'être complexe. Elle doit simplement être connue de tous :

• Le rédacteur : souvent le Data Architect ou l'ingénieur qui porte le sujet, il prépare la fiche, décrit les options et propose une décision.
• Les personnes consultées : les équipes techniques concernées et, quand la décision touche un usage, le Data Owner du domaine.
• Le décideur : la personne ou l'instance qui accepte la décision, selon son ampleur.
• Le garant du registre : la personne qui veille à la tenue du registre, à la cohérence des statuts et à la relecture périodique.

Les décisions les plus structurantes remontent au Chief Data Officer ou à l'instance qui pilote l'architecture des données. Les autres se prennent au niveau de l'équipe, avec la même exigence de documentation.

Les décisions qui sortent du champ technique

Certaines décisions d'architecture engagent l'organisation au-delà de l'équipe technique. Confier la production d'une donnée à une direction métier, imposer une règle de conservation ou restreindre un accès modifie les responsabilités et les pratiques de travail.

Ces décisions ne peuvent pas être prises par la seule équipe data, même si elles s'expriment dans un vocabulaire technique. La fiche doit alors indiquer explicitement les directions consultées et l'instance qui a tranché.

👉 À lire aussi : Plateforme Data et gouvernance : ce qui relève de la technique… et ce qui n'en relève pas

Faire vivre le registre des décisions d'architecture dans la durée

Un registre de décisions ne vaut que s'il est tenu et consulté. Beaucoup d'initiatives démarrent avec enthousiasme et s'arrêtent au bout de quelques mois, faute de rituel qui les fasse vivre.

Relire le registre à chaque révision de l'architecture cible

Le moment naturel pour relire le registre est la révision de l'architecture cible. Lorsqu'on définit l'architecture des données cible à partir des usages, chaque fin de palier est l'occasion de vérifier si les conditions de révision des décisions en vigueur sont réunies.

Cette relecture répond à une question simple pour chaque décision structurante : les hypothèses qui la justifiaient sont-elles toujours vraies ? Si oui, la décision reste en vigueur. Si non, une nouvelle fiche est ouverte.

Les signes qu'un registre n'est plus tenu

Un registre abandonné se reconnaît à quelques signes. Les repérer tôt permet de relancer la pratique avant que le registre ne perde toute crédibilité :

• Aucune fiche récente : les dernières décisions datent de plusieurs mois, alors que l'architecture a continué d'évoluer.
• Des statuts incohérents : des décisions acceptées qui ne correspondent plus à ce qui tourne en production.
• Des débats tranchés hors du registre : les choix importants se font en réunion et ne donnent lieu à aucune fiche.
• Un registre que personne ne cite : les équipes ne renvoient jamais à une fiche pour justifier un choix.

Un registre bien tenu se lit d'un coup d'œil. Chaque décision y porte un numéro, un statut, un décideur et une condition de révision, et une décision remplacée reste visible avec un renvoi vers celle qui lui succède.

Documenter les décisions d'architecture des données ne ralentit pas les équipes. Cela leur évite de reprendre les mêmes discussions, protège les choix qui ont été mûrement réfléchis et rend possible leur révision quand le contexte change. Le registre devient alors la mémoire de l'architecture, indépendante des personnes qui l'ont construite.

La pratique demande peu : une fiche courte pour chaque choix coûteux à défaire, un emplacement unique et un rituel de relecture. Elle produit ses effets au premier départ d'un membre clé de l'équipe, au moment précis où les organisations qui ne l'ont pas mise en place découvrent ce qu'elles ont perdu.