Le gabarit d'un ADR est la partie facile. La partie difficile, c'est d'en écrire un qu'un inconnu, des mois plus tard, ouvrira, lira jusqu'au bout, et croira.
Un dépôt rempli d'ADR que personne ne relit est pire que pas d'ADR du tout. Il donne l'apparence de l'hygiène décisionnelle sans la substance : la case est cochée, le rituel respecté, et les documents dorment. Le jour où une décision est remise en cause, personne ne pense à les rouvrir — parce que l'expérience a appris qu'on n'y trouvait rien.
La structure d'un ADR — ses cinq sections : contexte, contraintes, besoins, alternatives, décision — est un sujet que nous avons traité ailleurs. Elle s'assimile en une lecture. Ce texte porte sur l'autre moitié du problème, la moins discutée : la manière de rédiger un ADR pour qu'il franchisse le temps.
Le lecteur n'est pas vous
Tout commence par un déplacement. L'auteur d'un ADR écrit spontanément pour lui-même : il a le contexte en tête, il connaît les personnes mentionnées, il sait ce qui allait de soi cette semaine-là. Son lecteur n'a rien de tout cela. C'est quelqu'un qui rejoint l'équipe dans dix-huit mois — ou c'est l'auteur lui-même, dix-huit mois plus tard, qui a tout oublié. Cette personne ne dispose que du texte. Si le texte suppose un contexte qu'elle n'a pas, il ne lui transmet rien.
Écrire un bon ADR, c'est écrire pour cet inconnu. La plupart des défauts qui suivent sont des variantes d'un même oubli : avoir écrit pour soi.
Les pièges
Le plus courant est l'ADR rédigé après coup. La décision a été prise il y a trois semaines, le code est livré, et l'on rédige le document pour « garder une trace ». Le résultat se reconnaît au premier coup d'œil : pas d'alternatives réelles, un contexte qui connaît déjà sa fin, un ton sans la moindre incertitude. Cet ADR ne consigne pas une décision, il la justifie. Or un lecteur futur n'a pas besoin d'un plaidoyer — il a besoin de comprendre un raisonnement. Un ADR s'écrit pendant qu'on hésite encore, au moment où l'on ne sait pas si l'on a raison. L'incertitude qu'on y laisse transparaître n'est pas une faiblesse : c'est ce qui le rendra crédible.
Vient ensuite le contexte qui contient déjà sa conclusion. La section « contexte » devrait exposer un problème ; trop souvent elle vend une réponse. Les faits y sont choisis, ordonnés et éclairés de telle sorte que le choix final paraisse inévitable. Le test : masquez la section « décision » et faites lire le contexte seul. Si le lecteur devine la décision, demandez-vous pourquoi. Parce que le problème y mène réellement — ou parce que vous avez disposé le décor ?
Le piège jumeau est l'alternative en homme de paille. L'option retenue reçoit trois paragraphes nuancés ; les options écartées, une phrase expéditive chacune. Un ingénieur expérimenté détecte ce déséquilibre immédiatement, et dès qu'il le détecte, il cesse de faire confiance au document entier. La crédibilité d'un ADR ne tient pas à la qualité de son option gagnante ; elle tient à l'équité avec laquelle les perdantes ont été traitées. Une alternative qu'on écarte mérite qu'on énonce d'abord ce qu'elle avait pour elle.
Le mauvais niveau de détail fait échouer un ADR par deux extrémités opposées. Trop vague : « nous utiliserons une file de messages pour la montée en charge » — laquelle, quelle charge, la montée en charge de quoi ? Le lecteur ne peut rien reconstruire. Trop dense : l'ADR reproduit des tableaux de benchmark, des comptes-rendus de réunion, une revue de littérature. Le lecteur se noie et referme. Le bon niveau est celui qui rend la décision reconstructible et le compromis visible — pas un mot de plus. Un ADR n'est ni un document de conception ni un postmortem.
Le jargon non daté est un défaut plus discret, et redoutable. « Nous avons repris l'approche du chantier de synchronisation plateforme. » Qui ? Quelle approche ? Le raccourci interne que toute l'équipe comprend aujourd'hui sera du bruit dans deux ans, quand les personnes auront tourné et le chantier sera oublié. Développez les sigles une fois. Nommez les systèmes par leur nom réel. Une référence à un projet, une personne ou un outil doit rester lisible pour quelqu'un qui ne les a jamais connus.
Reste la décision sans prix. Une section « décision » qui n'énumère que des avantages est incomplète, et le lecteur le sait — parce qu'il rencontrera le coût tôt ou tard dans le code, et se demandera alors si vous l'aviez vu venir. Toute décision d'architecture achète quelque chose à un prix. Nommer ce prix n'affaiblit pas la décision : cela prouve qu'elle a été prise les yeux ouverts.
Écrire pour être relu
Quelques habitudes simples corrigent la plupart de ces défauts.
Écrivez le contexte en premier, avant d'avoir tranché, si l'ordre des événements le permet. Formuler honnêtement le problème change parfois la décision — et c'est l'ADR qui fait son travail avant même d'être terminé.
Écrivez les alternatives avant la décision. Dans l'autre sens, les alternatives deviennent des justifications rétroactives : on les choisit pour qu'elles perdent. Écrites d'abord, elles restent un vrai comparatif.
Tenez la longueur. Une page. Un ADR qui déborde signale soit une décision encore floue, soit plusieurs décisions empilées. Découpez, ou clarifiez.
Écrivez en clair. Pas de prudence dissimulée derrière le jargon, pas d'abstraction là où un chiffre, un nom ou une date ferait l'affaire. Là où vous êtes incertain, écrivez-le : « nous ne savons pas encore si » est une information, pas un aveu.
Et donnez un statut net au document — proposé, accepté, remplacé. Un ADR sans statut clair est un piège : le lecteur ne sait pas s'il consulte une décision vivante ou un brouillon abandonné.
Le test
L'anatomie d'un ADR se vérifie en le confiant à un nouvel arrivant. Sa rédaction se vérifie autrement. Posez-vous une seule question : si vous trouviez cet ADR écrit par quelqu'un d'autre, à propos d'un système dont vous venez d'hériter, lui feriez-vous confiance ? Si oui, rédigez les vôtres ainsi. Si vous vous surprenez à être sceptique — sur les alternatives trop vite écartées, sur le contexte trop orienté, sur l'absence de coût — vous savez déjà quoi corriger.
schema est le carnet d'architecture de newline. Sa page de gauche porte un gabarit ADR, sa page de droite une grille de schémas — une décision par double page.