Notre histoire avec les ADR

Il existe déjà beaucoup d'articles sur les ADR, notamment cet excellent article de github sur l'importance des ADRs : Why Write ADRs

Notre article est un retour d'expérience sur les problèmes que nous avons rencontrés depuis la mise en place en 2016, les solutions que nous avons tentées. Ecrire un ADR est simple en soit, mais se donner le temps de le faire et de le faire régulièrement est beaucoup plus compliqué. Yoann vous raconte pourquoi.

🧐 Chers amis lecteurs, permettez-moi de vous parler d'un sujet qui, à première vue, peut sembler ennuyeux et technique, mais qui est en réalité d'une grande importance pour tout développeur informatique sérieux : les Architectural Decision Records, ou ADR pour faire court.

Maintenant, vous pourriez vous demander : pourquoi diable est-ce important ? Eh bien, laissez-moi vous donner un exemple concret. Nous travaillons avec un client depuis plusieurs années avec une équipe de quatre développeurs et développeuses. Au fil du temps, de nombreuses décisions architecturales seront prises : quel framework utiliser, quelle base de données choisir, quelles couches d'abstraction créer, et ainsi de suite.

🤓 C'est là qu'interviennent les Architectural Decision Records (ADR). Les ADR sont des documents qui enregistrent les décisions prises lors du développement de logiciels. Ils fournissent une trace de l'évolution de l'architecture du logiciel, y compris les raisons pour lesquelles certaines décisions ont été prises, les options qui ont été considérées et les avantages et les inconvénients de chaque option.

Si ces décisions ne sont pas documentées de manière cohérente, il peut être très difficile pour un nouveau développeur de comprendre pourquoi les choix ont été faits et comment les différentes parties du système interagissent.

😡 Cela peut entraîner des retards, des erreurs et des coûts supplémentaires, sans parler de la frustration des développeurs qui doivent naviguer dans un code sans aucune documentation claire.

Mais attendez, il y a plus ! Les ADR ne sont pas seulement utiles pour les nouveaux développeurs. Ils peuvent également être un outil précieux pour les développeurs expérimentés qui doivent se rappeler pourquoi ils ont pris certaines décisions, ou pour les architectes logiciels qui cherchent à évaluer les choix qui ont été faits lors de la conception du système.

🤝 En outre, les ADR peuvent également aider à résoudre les conflits entre les membres de l'équipe de développement. Si une décision est remise en question, les ADR peuvent fournir des informations sur les raisons pour lesquelles cette décision a été prise et aider à trouver une solution acceptable pour tous.

Voici un exemple d'ADR que l'on peut faire à KNP pour se donner une idée:

🦾 Énoncer le contexte de la décision à prendre
🦾 Décrire la problématique à adresser
🦾 Lister les contraintes qui influencent la décision finale
🦾 Lister les différentes options à discuter
🦾 Décider quelle sera l’option retenue après le débat

💬 Chez KNP Labs, un ADR permet de discuter. L'ADR est utilisé comme déclencheur d'une discussion entre collègues du même projet mais aussi de façon plus large entre tous les KNPeers dans le slack 'general' si le besoin se fait sentir. Ceci permet de capitaliser sur l'expérience de tous les KNPeers et en même temps, de diffuser la connaissance hors équipe projet. Elle n'est pas obligatoire, mais fortement conseillée.  

Alors, la prochaine fois que vous travaillez sur un projet, proposez de documenter chaque décision architecturale dans un ADR. Votre équipe de développement future vous remerciera. 🥰

D'ailleurs, nous utilisons depuis 2020 les decision records d'une manière générale pour documenter nos changements de processus chez KNP.  

Plus d'infos sur les ADRs

• Homepage of the ADR GitHub organization
• A useful template

Nous aimons partager notre expérience. Si vous avez une équipe qui cherche à approfondir ses connaissances, faites un tour sur notre page de formations.