Tout d'abord qu'est-ce qu'un ADR ?
La base de notre métier est de faire des choix : choix de technologie, choix d'architecture, choix d'implémentation...
Certains sont plus impactants que d'autres.
Le but d'un ADR est de documenter et de tracer le raisonnement derrière ces choix, en gardant le contexte du niveau de connaissance et de maîtrise du sujet au moment de ce choix.
Quel était mon problème ? Quelles étaient les différentes solutions envisagées ? Quels éléments nous ont amenés vers ce choix ?
Quel formalisme pour un ADR ?
Un ADR, c'est un document texte, facile à partager au sein de l'équipe (dans un wiki ou dans un repository par exemple).
C'est un document immuable, il n'a pas vocation à être mis à jour, au mieux le statut peut changer si cette décision est remplacée par une autre.
Le titre de l'ADR doit être explicite :
- choix_langage_backend
- choix_base_de_données
- gestion_des_dates
- format_des_logs
Décrivez clairement le contexte, pourquoi cette décision se pose, quel problème / contrainte essayons nous de résoudre ?
Décrivez le raisonnement qui vous amène à votre décision, n’hésitez pas à lister les expérimentations que vous avez faites, les articles sur lesquels vous vous êtes basés, tout ce qui vous permettra de comprendre votre décision si vous relisez l'ADR dans 6 mois.
Ce sont pour moi, les trois parties les plus importantes d'un ADR : titre, contexte, raisonnement/décision
Vous pouvez également décrire les conséquences qu'aura ce choix (par exemple nouvelle contrainte ou nouvelle complexité).
Vous pouvez aussi ajouter un statut à votre ADR (accepté, rejeté, déprécié, remplacé...).
Vous pouvez trouver des modèles d'ADR beaucoup plus détaillés sur internet, mais au final c'est vous et votre équipe qui allez les écrire et les lire donc choisissez les rubriques qui sont pertinentes pour vous.
Conclusion
Dans un contexte en constante évolution, où nous apprenons de nouvelles choses régulièrement (sur les besoins des utilisateurs, sur les technos, ...), pouvoir pourquoi et comment tel ou tel choix a été fait est important pour une équipe et sa compréhension de son produit.
C'est aussi une source d'information pratique pour les nouveaux arrivants dans l'équipe.
D'un point de vue personnel, chez Avalon Lab, nous sommes des prestataires, nous accompagnons des entreprises et porteurs de projets qui n'ont pas forcément d'équipe technique.
Dans ce cas, les ADR nous permettent de documenter tous les choix technologiques et d'architectures que nous prenons, car finalement ce n'est pas nous qui allons vivre avec ces choix, mais bien les développeurs·euses qui seront recruté·e·s plus tard par le client.
Les ADR leurs permettrons de comprendre comment et pourquoi le produit est ce qu'il est.
Pour aller plus loin sur le sujet des ADR :
Top comments (0)