Gagner l'estime des futurs développeurs en rédigeant des ADR

Pourquoi on a mis ça en place déjà ?

euh… ben… je ne sais plus trop, c’est historique ?!

Un Architecture Decision Record (ADR) est un document qui saisit une décision, y compris le contexte dans lequel la décision a été prise et les conséquences de l'adoption de la décision.

Chez Marmelab, une poignée d'équipes utilisent les ADR pour documenter leurs décisions. L'une de ces équipes, dont je fais partie, travaille sur le site arte.tv. Nous nous concentrons sur le site web, l'API ainsi qu'une administration pour fournir aux utilisateurs les différents programmes. Le projet étant conséquent, nous sommes nombreux à travailler dessus, et ce sur des périodes différentes. Il est donc impératif de réferencer chacune de nos décisions.

Les ADR sont de simples fichiers Markdown

Rien de fantaisiste. C'est un format standard qui peut contenir des hyperliens et des images. Bien sûr, vous pouvez choisir le format qui convient le mieux à votre équipe.

Je vous recommande d'enregistrer les ADR avec le projet. Créez un dossier adr au sommet de votre projet et commencez à saisir les décisions importantes que vous prenez.

Un ADR comporte 5 éléments essentiels :

• Le titre, une courte phrase pour résumer la décision prise.
• La date, utile pour contextualiser.
• Le contexte, qui décrit les forces en jeu. Ces forces peuvent être technologiques, politiques, culturelles, basées sur des projets, etc. Il existe probablement des tensions et le contexte devrait les refléter de manière non biaisée. Ainsi, il permet à l'équipe de comprendre que la décision est la plus adaptée au moment où elle a été prise, même si elle peut être caduque le lendemain.
• La décision, c'est le point principal du document : rendre cette décision explicite pour les futurs responsables.
• Les conséquences, chaque décision a des conséquences, bonnes ou mauvaises. Encore une fois, il convient de faire attention à la formulation utilisée. Ce ne sont pas des jugements de valeur mais des déclarations de faits. Il est donc important d'être le plus proche possible de la réalité.

C'est tout !

Par exemple sur Arte, nous avons ajouté une partie décideurs et une partie références externes. Voici le tout premier ADR écrit sur le projet:

# 1. Manage Arte Documentation with ADRs

Date: Today date

Deciders: Alexis, François, Lucas, Maxime

Pull Request: [#number](pull-request-link)

## Status

2020-01-14 accepted

## Context and Problem Statement

We find it difficult to maintain overall documentation on Arte projects. We decided to document the code with [JSDoc](https://jsdoc.app/) and tests. But we keep only a few traces of architecture decisions.

We make several decisions informally during the daily meetings. We need to find a way to keep track of these decisions.

## Considered Options

-   Using the [Arte wiki](wiki-link)
-   Setting up a real documentation of the project, for example with a [docusaurus](https://docusaurus.io/)
-   Using [ADRs](https://adr.github.io/)

## Decision Outcome

Chosen option: "Using ADRs", because it seems to be the fastest maintainable solution. ADRs can follow the Pull Request rythme.

### Positive Consequences

-   A follow-up of the architectural decisions taken on the project
-   The ADR format is light and corresponds to our development methods.
-   The structure of the ADRs is comprehensible and facilitates use and maintenance.
-   The ADR project is well maintained.

### Negative Consequences

-   A bit of extra work for the developers who will have to take some time to write the ADRs.

## Links

-   [Architectural Decision Records](https://adr.github.io/)
-   [Markdown Architectural Decision Records](https://adr.github.io/madr/)

Par ailleurs, il existe également d'autres templates que vous pouvez retrouver ici.

C'est génial! Mais quel type de décisions ?

Vous vous dites peut-être : "Les ADR, c'est génial ! C'est exactement ce dont mon équipe a besoin pour faciliter la prise de décision ! Mais quel type de décisions doit-on documenter ?"

Les ADR ne concernent pas seulement les décisions d'architecture, mais aussi les choix technologiques, de modélisation du modèle métier, des optimisations, etc.

Chaque fois qu'une décision est prise, la rédaction de l'ADR nécessite que tous les membres de l'équipe s'accordent sur les éléments importants qu'ils souhaitent notifier, d'autant plus si cette décision a un impact majeur sur le projet.

Quels sont les avantages ?

Depuis l'adoption des ADR, nous avons observé de nombreux avantages, en voici quelques-uns :

Intégration

Les futurs membres de l'équipe sont aptes à lire un historique des décisions et de comprendre les processus de réflexion qui mènent à l'état actuel du projet.

Par exemple, en 2019, nous avons décidé d'unifier les standards de développement javascript. Nous avons pris cette décision lors d'une de nos réunions. Après avoir créé un package eslint, nous l'avons expérimenté sur nos applications. Quelles sont les conséquences de cette décision ? Les futurs développeurs arrivent sur une base de code harmonisée et ils peuvent comprendre le choix derrière les différentes règles de linting.

Transfert de connaissances

Nous travaillons dans un environnement agile où nous avons pour objectif d'apprendre rapidement. Dans ce cadre, nous n'hésitons pas à mettre en œuvre des changements organisationnels pour répondre aux besoins de nos clients. Lorsque notre équipe change, nous devons parfois transférer le savoir d'un membre à l'autre.

Dans le passé, beaucoup de contextes/connaissances étaient perdus lorsque cela se produisait. Cela pouvait engendrer une baisse de la productivité ou une reprise plus compliquée du projet. Ce problème est devenu moins récurrent avec l'introduction des ADR. Les nouveaux membres peuvent rapidement comprendre comment et pourquoi l'architecture du système a évolué, en se référant aux ADR.

Communication

Les ADR permettent aux équipes de s'aligner plus facilement avec les pratiques d'Arte. Ainsi, nous évitons la variance des solutions et nous empêchons de répéter les erreurs du passé.

Par exemple, une des équipes d'ARTE a pu lire et adopter Ramda grâce à l'ADR que nous avons écrit sur Ramda vs lodash.

JUST DO IT

Vous travaillez sur un système qui vous dépasse et qui manque de documentation ?

Voici ce que vous pouvez faire lorsque vous retournez au travail :

• Installez adr-tools (ou un autre cli)
• Lancez la commande adr new utilisation adr
• Ouvrez une Pull Request
• Ajoutez le lien vers cet article dans votre description PR
• Discutez avec votre équipe des avantages de l'utilisation des ADR

Les futurs responsables de la maintenance vous en seront reconnaissants, ainsi que vos futurs collègues.

Conclusion

À chaque démarrage ou changement de projet, je lis et j'écris des ADR. Je suis adepte de cette méthode de documentation. J'ai cité trois avantages à l'utilisation des ADR, cependant il en existe d'autres, que vous pourrez entrevoir si vous décidez de sauter le pas.