Architecture Decision Record

Enregistrer ses choix maintenant pour ne pas se chercher des poux plus tard

Ne cherchez pas de contrepetterie dans ce titre. En disant cela, vous êtes tenté bien sûr d’en trouver une. Curieusement l’attirance pour l’interdit fonctionne souvent mieux que l’obligation.

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. Il revient assez souvent que l’on me dise que dans les projets agiles, la documentation est trop incomplète voire 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 est de compléter ou améliorer la documentation technique existante. Lorsqu’elle est totalement absente, il suffit d’en avoir l’idée et la recette, 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, comme la remise en cause de 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

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:

  • Une série de posts consacrés à l’architecture logicielle dont un à sa documentation

Bibliographie:

  • Philippe Krutchen - Managing Technical Debt
  • Agile Technical Practices