Pourquoi tenir à jour un Architecture Decision Records (ADR) ?

En tant que développeurs avisés, au fil du temps, lorsqu’on devient senior et qu’on commence à accumuler une bonne expérience, on a envie tout naturellement de s’améliorer et d’affiner nos pratiques quotidiennes pour gagner en productivité. Décider de tenir à jour un Architecture Decision Records pourrait métamorphoser vos projets web…

On le sait tous, documenter le code est un aspect essentiel du développement logiciel. C’est crucial pour de nombreuses raisons pour : 

• les autres développeurs qui viendront après vous travailler sur le logiciel,
• prendre en main facilement le code, 
• la maintenance, 
• etc.

Il existe différentes méthodes pour documenter un logiciel, une application web, une application mobile, ou tout autre projet informatique. L’une des méthodes les plus efficaces s’appelle les Architecture Decision Records, ou ADR en abrégé.

Pourquoi la documentation logicielle est-elle si importante ?

Avant de rentrer dans le détail de ce qu’est un ADR, nous allons regarder de plus près les raisons qui rendent la documentation logicielle importante. Vous le savez, on rabâche très souvent aux différentes équipes projet de créer et de mettre à jour de façon rigoureuse une documentation logicielle… Mais en général, c’est à reculons que les membres se penchent sur le sujet…

Au-delà de la capitalisation du savoir et des connaissances, qui est un aspect très important dans les projets et qui est souvent mis de côté, il y a d’autres éléments, et même des risques, qui peuvent être couverts grâce à la documentation logicielle.

Pour commencer, il y a le risque que toute l’information ne soit détenue que par un seul et même expert. Ce qui signifie que sur la durée il va être très compliqué de se passer de cette personne, voire de la remplacer un jour.

De même, lorsqu’il n’y a pas de documentation sur le logiciel, cela crée des coûts d’entrée importants pour la prise en main du logiciel, donc des coûts supplémentaires. En effet cela va demander de former et d’informer tout nouvel utilisateur ou développeur rentrant sur le projet.

À ceci s’ajoute une vraie perte de connaissances sur le logiciel. Un petit peu comme une transmission du patrimoine qui n’aura pas été faite et qui va impacter le bon développement futur du logiciel.

Pour développer votre solution digitale vous pouvez compter sur nos dev offshore au Vietnam, à Madagascar et à Maurice.

Et enfin, une perte de temps. 

Forcément, devoir former, informer les nouveaux développeurs et les nouveaux utilisateurs concernant le fonctionnement du logiciel, devoir plonger dans le code pour comprendre pourquoi telle fonctionnalité a été développée ainsi, pourquoi telle autre l’a été autrement, représente une grosse perte de temps. Et c’est même d’ailleurs pour cette raison, que bon nombre d’entre nous préfèrent développer from scratch que de mettre les mains dans un logiciel qu’on n’a pas développé nous-même et qu’on a pas vu se construire.

C’est pour cette raison que non seulement un ADR est important, mais aussi tout type de documentation :  

• spécifications fonctionnelles ou techniques,
• guide de rédaction, 
• charte éditoriale, 
• tutoriel, 
• cahier des charges, 
• cahier de recettes, 
• manuel utilisateur,
• plan de test, 
• suivi de projet, des procédures,
• etc. 

Découvrir les Architecture Decision Records (ADR)

Nous allons étudier cette méthode/documentation pour comprendre comment ça fonctionne.

Les 3 raisons qui poussent à utiliser les Architecture Decision Records (ADR)

Quelles sont les principales raisons pour lesquelles on utilise un ADR dans les projets informatiques ? 

Les ADR dans les projets logiciels sont utiles pour plusieurs raisons. Ils vont permettre d’assurer une cohérence globale sur le projet et de maintenir une vision claire pour les futurs développements et les futures évolutions du projet.

Ils vont faciliter l’intégration de nouveaux développeurs sur le projet. Lorsque des nouveaux développeurs front-end ou back-end vont intégrer l’équipe, il sera plus facile pour eux de prendre la main en s’appuyant sur ce document.

Enfin, dernier point, un ADR aide à prendre des décisions futures. En s’inspirant de l’historique des anciennes décisions architecturales prises sur l’application, il est plus facile pour le client et la technique d’entrevoir l’avenir.

Qu’est-ce qu’un Architecture Decision Record ?

Pour simplifier le concept, l’ADR, c’est un peu comme un journal, vous pouvez l’imaginer comme le tableau de bord d’un projet. Dans ce tableau, on va retrouver toutes les décisions qui ont été prises par l’équipe de développement sur le projet. 

C’est, vous l’aurez compris, un outil qui est vraiment très puissant, surtout dans les projets où les équipes sont multidisciplinaires.

Dans l’ADR, on peut retrouver différentes informations, telles que :

• Qui sont les décideurs ?
• Quel est le contexte ?
• Quel est l’historique du projet ?
• Quelles sont les alternatives envisagées, les idées envisagées, les hypothèses émises ?
• Quelles sont les forces et les faiblesses de chaque hypothèse ?
• Quelles décisions ont été prises et sur quels critères ?
• Quels ont été les feedbacks récoltés au cours des échanges, des discussions et des réunions ?
• Quelles sont les conséquences des décisions qui ont été prises tout au long du projet ?

L’ADR, une documentation événementielle

L’ADR, c’est une rédaction événementielle. On sait très bien qu’a quotidien, pour les c’est rébarbatif et chronophage de maintenir à jour une telle documentation. Mais il faut garder en tête que l’ADR est vraiment comme un journal de pilotage du projet, un peu comme celui qu’un capitaine de navire tiendrait pour garder une vision claire de sa trajectoire.

De plus, cette documentation n’est jamais périmée, car elle explique et documente pourquoi chaque décision a été prise sur le projet, offrant ainsi un contexte précieux pour les décisions futures.

À la recherche de votre prochain dev offshore pour un projet logiciel ? Vous avez frappé à la bonne porte, contactez Quentin et dites lui de quoi vous avez besoin.

Exemple d’un ADR

Voici un exemple concret d’une documentation ADR typique :

Date : 13 novembre 2024
Décision prise par : un architecte IA, les développeurs, et le Product Owner

Contexte

Notre équipe fictive travaille actuellement sur un projet de reconnaissance d’image basé sur l’intelligence artificielle, nommé PictureZy (un condensé de « Picture » et « Easy »). 

Pour faire évoluer et rendre l’application plus performante, nous avons dû choisir entre deux frameworks d’apprentissage automatique, chacun avec ses avantages et inconvénients. 

Le défi principal est de trouver une solution optimale pour réussir à gérer de très grandes quantités de données visuelles en temps réel.

Les options envisagées

Framework A

• Avantages : excellente optimisation pour le déploiement sur GPU (processeur graphique), particulièrement adaptée aux environnements de production exigeants.
• Inconvénients : complexité accrue pour intégrer des pipelines de pré-traitement et de post-traitement.

Framework B

• Forces : connexion facile avec d’autres frameworks, générant plus d’agilité et de flexibilité pour le développement et le déploiement sur différents périphériques.
• Faiblesses : performances légèrement inférieures sur les GPU, avec des limitations possibles pour l’optimisation en temps réel.

Décision prise

Nous avons finalement décidé d’opter pour le framework A. Ce choix a été motivé par ses performances en matière de traitement d’images en temps réel, une caractéristique essentielle pour notre application.

Bien que l’intégration soit plus complexe, nous pensons gagner en rapidité et en efficacité, répondant ainsi aux exigences du client.

Conséquence

Pour gagner en efficacité, l’équipe a décidé de mettre en place un workflow automatisé pour gérer les étapes de pré-traitement et de post-traitement. Chaque étape sera documentée pour simplifier la compréhension, la maintenance et les mises à jour futures.

Note additionnelle

Un vocabulaire commun a été établi au sein de l’équipe pour une meilleure compréhension entre tous :

• « En cours » : la fonctionnalité est en développement ou en test sur la feature branche.

• « Accepté » : le développement a été validé et fusionné dans la branche principale après revue.

• « Suspendu » : l’élément est mis en pause pour réévaluation.

Références :

dev.to : How Senior Software Engineers Document Their Project

thecodingmachien.com : Bonnes pratiques pour documenter son code PHP en utilisant ADR (Architecture Decision Records)

blogocto.com : Architecture Decision Record : on commence aujourd’hui

ripplemotion.fr : L’IMPORTANCE DE LA DOCUMENTATION LOGICIELLE !