Transmettre en asynchrone : revue de code, ADR et docs-as-code

Revue de code, ADR, docs-as-code, runbooks, postmortems : les modes de transmission qui ne demandent ni le même lieu ni le même moment, et qui produisent une trace durable — à condition de bien s'y prendre.

Dans le guide des modes de collaboration, nous avons posé une règle : le savoir explicite se transmet en asynchrone. Là où les modes synchrones font passer l’intuition par le contact, les modes asynchrones fixent ce qui peut être écrit — et produisent une trace qui survit aux départs. Encore faut-il éviter le piège classique : une documentation que personne ne lit et que plus personne ne met à jour. Cet article détaille les pratiques qui marchent, et pourquoi.

I. La force et la limite de l’écrit  

L’écrit a un avantage qu’aucun mode synchrone n’égale : il ne dépend de personne. Il se lit à trois heures du matin pendant un incident, six mois après le départ de son auteur, par quelqu’un qui n’était pas là quand la décision a été prise. C’est le socle de la mémoire d’une équipe.

Mais l’écrit a deux ennemis. Le premier est l’altération : une documentation qui ne suit pas le code devient un piège, car un lecteur ne peut pas distinguer ce qui est à jour de ce qui ne l’est plus. Le second est l’illusion de complétude : croire qu’un document capture une expertise, alors qu’il n’en fixe que la partie explicite.

D’où le fil rouge de cet article : les bons modes asynchrones sont ceux qui luttent contre l’altération — en rapprochant l’écrit du code, en le rendant vivant, en documentant le pourquoi plutôt que le comment.

II. La revue de code : transmettre sans réunion  

La revue de code est le mode de transmission le plus fréquent — et le plus gâché. Trop souvent, elle se réduit à une case à cocher : « ça compile, les tests passent, j’approuve ». On y valide le quoi, on y perd le pourquoi.

Or une revue bien menée est un canal de transmission puissant :

• Pour l’auteur, expliquer son intention dans la description de la pull request force à clarifier sa pensée.
• Pour le relecteur, lire du code qu’on n’a pas écrit est la façon la plus régulière de découvrir des zones du système qu’on ne touche jamais.
• Pour l’équipe, les échanges en revue diffusent les conventions, les pièges connus, les préférences d’architecture.

Quelques principes pour qu’elle transmette vraiment :

• Commenter le pourquoi, pas seulement le quoi. « Renomme cette variable » transmet peu ; « renomme-la, car data masque le fait que c’est déjà filtré » transmet une règle.
• Poser des questions plutôt que des ordres. « Pourquoi ce choix ? » ouvre un échange ; « change ça » le ferme.
• Répartir les relecteurs. Si c’est toujours la même personne qui relit un domaine, on recrée un goulot d’étranglement — et un bus factor de 1 déguisé.
• Garder les revues petites. On relit sérieusement 50 lignes ; on survole 800. Une grosse pull request ne transmet rien.

III. Les ADR : documenter le pourquoi  

C’est la pièce maîtresse de la transmission asynchrone, et la plus négligée. Un ADR (Architecture Decision Record) est une courte fiche qui consigne une décision d’architecture au moment où elle est prise.

Le code dit ce que fait le système. Il ne dit jamais pourquoi on a choisi cette base de données, écarté cette bibliothèque, ou toléré ce contournement. Cette raison-là ne vit que dans la tête de ceux qui étaient là — et disparaît avec eux. C’est exactement la « barrière de Chesterton » : sans le pourquoi, un successeur ne sait pas s’il peut démolir la clôture.

Un ADR tient sur une page et suit un format simple :

• Contexte : quel problème, quelles contraintes au moment du choix ?
• Décision : ce qui a été décidé, énoncé clairement.
• Alternatives écartées : ce qu’on a envisagé et pourquoi on l’a rejeté — souvent la partie la plus précieuse.
• Conséquences : ce que la décision implique, y compris ses inconvénients acceptés.

Deux règles font toute la différence :

• Écrire l’ADR au moment de la décision, pas des mois après, quand le contexte s’est déjà évaporé.
• Ne jamais réécrire l’histoire. Un ADR est immuable : si une décision change, on en écrit un nouveau qui remplace l’ancien (« superseded by ADR-012 »). La chaîne des décisions raconte l’évolution du système — c’est une mémoire, pas un état.

Rangés dans le dépôt, à côté du code, les ADR forment le journal de bord que tout nouvel arrivant devrait pouvoir lire pour comprendre comment on en est arrivé là.

IV. Les docs-as-code : rapprocher la doc du code  

Le pire ennemi de la documentation, c’est la distance qui la sépare du code. Un wiki hébergé ailleurs, édité à part, relu par personne : il se dégrade en silence, et chaque information périmée sape la confiance dans tout le reste.

L’approche docs-as-code renverse le problème en traitant la documentation comme du code :

• elle vit dans le dépôt, en Markdown, à côté de ce qu’elle décrit ;
• elle est versionnée : on voit qui a changé quoi, et quand ;
• elle passe par la revue : une modification de code qui rend la doc fausse se corrige dans la même pull request ;
• elle peut être testée : liens morts, exemples de code qui ne compilent plus, etc.

Le bénéfice est double. La doc reste à jour parce qu’elle est mise à jour au même endroit et au même moment que le code. Et elle gagne en crédibilité : un lecteur peut faire confiance à un document dont il voit qu’il a été touché en même temps que le code qu’il décrit.

Une bonne documentation n’est pas celle qui est complète, c’est celle en qui on peut avoir confiance. La proximité avec le code est ce qui crée cette confiance.

V. Les runbooks : la mémoire opérationnelle  

Un runbook est une procédure d’incident écrite, testée, et accessible à tous : comment redémarrer ce service, restaurer cette base, réagir à cette alerte. C’est la traduction asynchrone d’un savoir que, sinon, un seul expert détient — et qu’on découvre manquer en pleine panne.

Un bon runbook :

• part d’un symptôme (« l’alerte X se déclenche ») et mène à des actions concrètes ;
• est testé hors incident — un runbook jamais essayé est une fiction rassurante ;
• est daté et revu, car une procédure périmée est plus dangereuse que pas de procédure du tout.

Son effet le plus précieux : il transforme la panique en gestes sûrs, et rend l’astreinte praticable par quelqu’un d’autre que l’auteur du système.

VI. Les postmortems sans blâme : apprendre des incidents  

Chaque incident est un savoir qui ne demande qu’à être capturé — à condition de ne pas chercher un coupable. Le postmortem sans blâme part d’un principe : les gens agissent au mieux avec l’information dont ils disposent ; si une erreur a été possible, c’est le système qu’il faut corriger, pas la personne.

Un postmortem utile décrit ce qui s’est passé, pourquoi le système l’a permis, et quels garde-fous durables en découlent. Publié et archivé, il devient une mémoire collective : la prochaine personne confrontée au même symptôme n’aura pas à réapprendre dans la douleur.

Sans blâme, les gens racontent la vérité — et c’est de la vérité qu’on apprend. Avec blâme, ils se protègent, et le savoir se perd.

VII. Comment les combiner  

Ces modes ne sont pas concurrents, ils forment une chaîne :

• une décision se consigne dans un ADR ;
• sa mise en œuvre passe par une revue de code qui en diffuse les détails ;
• son fonctionnement se documente en docs-as-code, à côté du code ;
• son exploitation s’outille d’un runbook ;
• et quand quelque chose casse, un postmortem referme la boucle en produisant un nouveau savoir.

Le point commun de toute la chaîne : rapprocher l’écrit de ce qu’il décrit, documenter le pourquoi, et garder chaque trace vivante. C’est ce qui distingue une documentation qui transmet d’une documentation qui ment.

Conclusion  

Les modes asynchrones ne remplacent pas le contact — ils fixent ce que le contact ne peut pas rendre permanent. Leur valeur ne tient pas au volume produit, mais à la confiance qu’on peut leur accorder : un ADR au bon moment, une revue qui explique, une doc collée au code, un runbook testé valent mille pages de wiki oubliées.

Retenez ceci : ce n’est pas écrire plus qui protège une équipe, c’est écrire ce qui dure, près du code, et le tenir vivant. C’est cet écrit-là qui parlera encore quand son auteur sera parti.

Useful links  

• Documenting Architecture Decisions — Michael Nygard
  L’article fondateur des ADR : format, motivation et exemples pour documenter le pourquoi d’une décision.

• adr.github.io — Architecture Decision Records
  Portail de référence sur les ADR : modèles, outils et variantes de format prêts à l’emploi.

• Google SRE Book — Postmortem Culture
  Le chapitre de référence sur les postmortems sans blâme : principes, pièges et exemples concrets.

• Write the Docs — Docs as Code
  Présentation de l’approche docs-as-code : outils, flux de travail et bénéfices d’une documentation traitée comme du code.