Mise en place des ADRs dans une équipe hétérogène de 5 personnes
Contexte
Dans le cadre d’une mission de 9 mois, j’ai eu l’occasion de travailler pour un client dans l’industrie. Ce qu’on appelle communément un “grand compte” 😏.
Qui dit grand compte, dit souvent 👀…
De l’historique, des procédures et de la documentation. Beaucoup de documentation. Je dirais même plus : un besoin insatiable de documenter tout ce qui est fait.
Dans ce type de structure, on retrouve aussi une inertie importante. Les changements prennent du temps.
C’est aussi dans ces entreprises que nous pouvons retrouver des turn-over régulier des équipes de développements. Ces équipes qui peuvent partiellement, ou complètement, être externalisé à des entreprises de services numériques (connu sous le doux nom d’ESN).
Ainsi, le besoin de documenter pour assurer les transferts de connaissances a une importance capitale tant sur les coûts de formation des nouveaux arrivants que sur leur charge mental 😶.
C’est pourquoi, des dérives peuvent se produire comme le fait de “sur-documenter”, de documenter “au cas où”, de demander aux développeurs de mettre à jour des sharepoints, excel, google drive, etc.
Or, les devs que nous sommes, n’aimons pas particulièrement travailler avec une diversité d’outil aussi prononcé pour de la documentation 😶.
L’équipe
- 1 développeur avec plus de 10 ans d’expérience
- 1 développeur junior avec 1 an d’expérience
- 1 développeur junior tout juste sortie d’école
- 1 lead dev (moi)
- 1 chef de projet (similaire à un product owner)
- 1 responsable de service
- 1 scrum master
Une solution de documentation à travers les ADRs
Qu’est ce que c’est ?
ADR pour Architecture Decision Records.
C’est, une typologie, un modèle de document qui facilite l’historique des décisions prises sur un projet. De la même manière que les RFCs.
RedHat a publié un très bon article sur pourquoi nous devrions utiliser les ADRs pour documenter nos décisions d’architecture il y a quelques années, je vous conseille de le parcourir !
Le but derrière une ADR est d’historiser un choix technique dans un contexte précis (politique, économique ou social donné).
Ainsi, cela permets, plus tard, lorsqu’un choix d’architecture sera critiqué, de mieux comprendre pourquoi.
Parce qu’il sera critiqué par un nouvel arrivant, nous le savons 😄.
La mise en place des ADRs permets de faciliter la documentation par les développeurs (et de les motiver à le faire 🙂).
Il existe des dizaines de modèles d’ADR. Je conseille de les parcourir et de regarder avec toute l’équipe lequel serait le plus adapté pour commencer.
En effet, ne faites pas l’erreur de sortir de suite l’artillerie lourde !
Il sera toujours possible de changer le format après quelques semaines ou mois de pratique (n’est-ce pas cela aussi, l’agilité ? 🙌).
Une petite matrice SWOT
Lors de l’argumentaire pour présenter cette manière de documenter, nous avons travaillé tous ensemble sur une matrice SWOT.
Autant pour convaincre des parties extérieur au quotidien de l’équipe que pour nous convaincre nous-même que nous étions dans la bonne direction 😁!
⬆ Forces:
- Historiser la décision et les décideurs
- Renseigner le contexte de la décision permets de responsabiliser
- Faciliter la compréhension des choix faits pour un nouvel arrivant
- Faciliter d’archivage des documents
↗ Opportunités:
- Simplifier la documentation pour les développeurs
- Historiser cette documentation au plus proche des outils des développeurs (dans un repo GIT par exemple)
⬇ Faiblesses:
- Le partage avec des parties prenantes externes (ce qui pourrait demander une duplication des informations ou une réécriture)
↘ Menaces:
- Overthinking
- Historiser tout et n’importe quoi (comme quelque chose qui n’est pas une décision d’architecture)
Où stocker ces documents ?
Importante question !
Sachant que ce sont les développeurs qui vont rédiger ces prises de décisions, il faut alors que les documents soient stocker au plus proche des outils qu’ils utilisent au quotidien.
Pourquoi ?
Parce que nous avons besoin d’être motivé à documenter 😇.
Ainsi, dans l’idéal, il faudrait stocker les ADRs sur GIT, dans le repository associé au projet !
Dans notre cas, nous avons fait un choix pragmatique : nous avions décidé de tout placer dans un wiki.
En effet, c’est Azure Dev Ops (ADO) qui était utilisé pour toute la gestion de projet et de code source.
Les personnes du projets qui n’étaient pas développeurs, étaient déjà habitués à travailler avec les wiki d’ADO.
Exemple de template
Dans notre cas, nous avons regardé ce qui existait déjà. Autant capitaliser sur les expériences des personnes qui ont déjà eu la problématique, non ?
Ainsi, nous sommes tombés sur ce modèle d’ADR.
Ce que nous avons apprécié dans ce modèle, c’est de permettre de noter les différentes options, avec les avantages et inconvénients de chacune de ces options.
Ci-dessous un exemple d’ADR que j’ai gardé dans la langue original de Shakespeare (en tant que développeur, notre métier nous demande d’être à l’aise avec l’anglais) :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
# 001 - Application hosted as a Windows Service.
## Title
Application will run as a Windows Service.
## **Status**
Accepted.
## **Summary**
**In the context of** the technical requirement of the production and usual habits of internal developers teams.
**facing** the need of being homogeneous between usages
**we decided for** running the application as a Windows Service.
**and neglected** any other options
**to achieve** better maintenance and collaboration with the infra team.
## **Context**
The targeted production stack is based on Windows Server.
We would like to have a industrial way to deploy it and ensure us that the infrastructure teams can easily apply their maintenance and monitoring plans.
The actual dev teams already use Windows Services but still, we would like to record the decision.
## **Options**
### Define app as a Windows Service
Good, because concept is already used by actual dev teams.
Good, because solution is native and supported by the targeted stack.
Good, because it is reliable.
Bad, because we can't precisely control if, other services required by our app, already run.
## **Decision**
Given the fact that:
- Actual dev teams is already used to manage Windows Service
- All the good points above
We choose to deploy and host our app as a Windows Service.
## **Consequences**
- we must find an efficient way to configure our CI pipeline to create the targeted package
- we should configure our CD pipeline to include a deployment script
- we should find a way to automatize the Windows Service creation, update, removal and the launch of it
### Deciders:
- ...
- ...
### Last state updated date: 03/01/2024
Conclusion
Il n’y a pas une seule solution, magique, qui résous tout.
Par exemple, dans d’autres équipes, une pull request / merge request est considéré comme étant une ADR.
Une décision est vivante, ainsi, il est possible et recommandé de la metre à jour au fur et à mesure du temps. Elle peut devenir depréciée par une autre décision d’ailleurs. Il sera donc pertinent de l’indiquer dans son état avec un lien vers la nouvelle décision.
Un réflexe à avoir lorsque l’on se demande ce qu’il faudrait historiser ou non une décision, serait de déterminer si nous sommes capable de mesurer cette décision.
En appliquant par exemple le principe SMART (encore un autre principe 🤷♂️ !).
Oui cela a bien fonctionné 👍.
Mais dans d’autres projets, avec d’autres enjeux politiques internes, financiers ou sociales, il aurait peut-être fallu envisager d’autres pistes.
Et si nous avons réussi ce changement, c’est bien grace à toutes les parties prenantes :
- l’instigateur de la solution 👋
- la remise en question de l’existant par l’équipe en place
- le choix de dupliquer l’information quand cela sera nécessaire
Ressources
- https://www.redhat.com/architect/architecture-decision-records
- https://blog.octo.com/architecture-decision-record/
- Scaling the Practice of Architecture, Conversationally (martinfowler.com)
- Documenting Architecture Decisions (cognitect.com)
- https://www.linkedin.com/pulse/what-architecture-decision-record-adr-do-i-need-how-useful-atmakur
- https://github.com/joelparkerhenderson/architecture-decision-record
- À lire pour l’approche philosophique
Je vous ai déjà parlé de ma règle universelle favorite, inspiré des scouts ? Sûrement pas assez 🙂.
Essayez de laisser ce monde un peu meilleur qu’il ne l’était quand y êtes venus. (Baden-Powell)