Architecture Decision Record

Ne cherchez pas de contrepetterie dans ce sous-titre !

En disant cela, vous êtes tenté bien sûr d’en trouver une. Curieusement l’attirance pour le défit ou l’interdit passe souvent avant l’exécution d’une directive ou même l’application d’un conseil.

Tout le monde se rappelle que dans le manifeste agile il est écrit “un logiciel qui fonctionne plutôt qu’une documentation exhaustive”. Cette phrase a autorisé à braver le caractère obligatoire et exhaustif de la documentation, par effet de balancier. Il revient d’ailleurs assez souvent que l’on me dise que dans les projets agiles, la documentation est trop incomplète voire complètement absente.

Peut-être que quelques injonctions pourraient vous influencer :

• “Surtout ne regardez pas les décisions d’architecture de l’équipe ! Vous risqueriez de devoir chercher à comprendre ou pire les rédiger vous-même si elles venaient à vous manquer !”

• “Ne demandez pas la documentation technique, vous risqueriez de mettre quelqu’un mal à l’aise et de mettre en doute la qualité du produit et donc du travail réalisé jusque là”

Vous avez probablement trouvé d’autres comportements automatiques en vigueur dans votre équipe, qui peuvent freiner l’amélioration de la qualité du produit, jusqu’au moment où …

Il arrive toujours un moment où l’on peut s’interroger sur les raisons de certains choix techniques qui s’avèrent présenter maintenant des limitations.

Il y a alors plusieurs attitudes possibles:

• continuer à se lamenter de cette méconnaissance jusqu’au prochain projet de refonte
• solliciter les développeurs d’origine pour déceler les raisons et pièges cachés
• faire des fouilles dans l’historique de gestion de configuration
• se lancer dans une expérimentation hasardeuse
• …

Une autre piste (plus responsable ?) est de compléter ou améliorer la documentation technique existante. Lorsqu’elle est totalement absente, il suffit d’en avoir l’idée, la recette et d’un peu de temps, pour commencer à combler ce manque.

Il ne sert pas à grand chose de documenter un choix technique antérieur pour lequel on n’a pas de réponse. Par contre, l’idée d’un changement, qui remet en cause l’existant, peut gagner à être documentée, structurée, en termes d’options à comparer et de processus à suivre.

De cette façon, au fil du temps, il est possible de disposer et maintenir les décisions importantes et toujours actives pour faciliter les nouvelles évolutions.

Modèle d’ADR

Il en existe plusieurs, celui-ci est attribué à Michael Nygard.

Title Status What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?

Context What is the issue that we’re seeing that is motivating this decision or change?

Decision What is the change that we’re proposing and/or doing?

Consequences What becomes easier or more difficult to do because of this change?

Références

Webographie:

• L’article d’InfoQ qui fournit un regard plus classique des ADR
• Une série de posts consacrés à l’architecture logicielle dont un à sa documentation
• L’article d’où j’ai tiré le template Bradjolicoeur

Bibliographie:

• Managing Technical Debt - Philippe Krutchen
• Agile Technical Practices Distilled - Pedro Moreira Santos, Marco Consolaro, Alessandro Di Gioia