Développement

Documenter le rationnel

Les décisions sont prises de manière orale ? Au sein de l'équipe ? Tout au long du projet ? Il s'avère que nos souvenirs sur cette décision changent dans le temps voire, pire, disparaissent.

Retours d’expérience de la communauté

Documenter pourquoi une image custom docker a été créée

Thibault Dassise

Avant l’application du principe

Un collègue avait créé un Dockerfile avec comme FROM une image custom provenant d'un container registry sur GCP, sans explication sur l'utilité d'utiliser une image custom de Node 17 plutôt que l'image officielle.

Après l’application du principe

Après discussion avec lui, il m'a expliqué que cette image était juste une image Node 17 sans aucune modification, mais qu'il avait procédé de cette manière pour éviter d'atteindre la limite des 100 pulls sur le Docker Hub.

J'ai donc ajouté un commentaire dans le Dockerfile pour expliquer pourquoi une image custom était utilisée afin de clarifier cette ligne capitale du fichier !

REX Documenter le rationnel via les ADR

Julian Didier - @theredfi_sh

Avant l’application du principe

Je travaille avec un client américain ayant une politique 100% remote, j’aide à la mise en place d’une équipe de QA pour des services backends.

Jusqu’ici toutes les décisions architecturales/techniques importantes étaient prises en réunions.

Résultat pas de traçabilité de l’information, tout doit être ré-expliqué aux nouveaux arrivants et bien entendu il y à une perte d’information importante impliquant des incompréhensions et de nouvelles réunions pour en rediscuter.

Après l’application du principe

J’ai proposé la mise en place d’ADRs (Architecture Design Records) pour pallier ce problème, d’autant plus que le remote nécessite une certaine organisation pour l’accès à l’information; tout le monde n’est pas sur la même timezone!

On gère les documents en markdown directement dans un dossier à la racine du projet concerné, comme ça pas besoin de chercher dans les milliers de pages Confluence!
‍

Résultat : un premier draft est versionné sous GIT via merge request, le document est discuté, revu et validé. Ces ADRs s’inscrivent dans le cycle de vie du projet et apportent tout le contexte nécessaire!