Skip to content
🌟 The full digital book is out: download it as soon as you buy 🌟
Development

Document the rationale

Are decisions made out loud? Within the team? All the way through the project? It turns out our memory of a decision shifts over time, or worse, disappears.

Field feedback from the community

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

Thibault Dassise

Before applying the principle

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.

After applying the principle

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

Before applying the principle

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.

After applying the principle

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!

documenter-le-rationnel-quelques-outils

Francois-Guillaume Ribreau

Before applying the principle

Pas de manière structurée de consigner et de partager des décisions d'architectures, de choix de stack, de design produit.

After applying the principle

Mise en place d'Architecture Design Record, dont voici quelques outils:

‍

Voici une liste de template alternatifs à ceux proposés dans le livre:

‍

Exemple d'ADRs:

‍

Exemple de documentation du rationnel dans le code source de Redis, son auteur applique ce principe de diverses manières au niveau du code:

‍

And you, what’s your field feedback?

If your feedback is validated, it will soon be published on the site.

Other principles

Same vein — click, bounce around.

See the whole category → All 60 principles →

This principle in our guides

Career guide How to become a Tech Lead: the transition guide Roles guide Tech Lead vs Engineering Manager: what’s the difference? Practical guide Tech Lead responsibilities: a practical guide