Des diagrammes d'architecture qui ne vieillissent pas : un workflow de documentation vivante

Chaque organisation d'ingénierie en a un : le diagramme d'architecture du wiki, exact pendant quelques semaines, il y a des années. Les nouveaux arrivants l'étudient, puis apprennent d'un collègue que la moitié des boîtes ont été renommées et que la file au milieu a été remplacée au printemps dernier. La plupart des bonnes pratiques de documentation d'architecture portent sur ce qu'il faut dessiner. Cet article traite de la partie la plus difficile : garder les diagrammes justes après le premier jet, avec un workflow qui les traite comme une documentation vivante plutôt que comme des livrables jetables.

Pourquoi la documentation d'architecture se périme

Les diagrammes se périment rarement parce que les gens sont paresseux. Ils se périment parce que le processus qui les entoure fait de l'obsolescence la norme.

• Ce sont des livrables ponctuels. Un diagramme est dessiné pour une revue de conception, le lancement d'une migration ou un audit. Une fois la réunion terminée, personne n'a de raison de le rouvrir.
• Les captures d'écran sont collées partout. Le fichier source reste sur l'ordinateur portable de quelqu'un, et un PNG finit dans le wiki, le document d'onboarding, trois présentations et un README. Il existe désormais cinq copies, et aucune n'est modifiable.
• Personne n'en est responsable. « L'équipe plateforme » n'est pas un responsable. Quand personne de précis n'est en charge, chacun suppose qu'un autre fera la mise à jour.
• Rien ne déclenche de mise à jour. Les changements de code passent par des pull requests, une revue et la CI. Les diagrammes ne changent que lorsque quelqu'un y pense, ce qui coïncide rarement avec le moment où le système change.
• Ils montrent trop de choses. Un diagramme avec chaque Pod, chaque file, chaque rôle IAM et chaque parcours utilisateur est obsolète le jour où il est terminé, car le moindre changement le rend faux.

Aucun de ces problèmes n'est d'abord un problème d'outil ; un meilleur outil de dessin ne remplace pas un responsable absent. Mais l'outil peut rendre le bon workflow bon marché ou coûteux.

Bonnes pratiques de documentation d'architecture pour des diagrammes vivants

Voici le workflow que nous recommandons. Il est volontairement tranché.

1. Une source de vérité par diagramme

Chaque diagramme existe à un seul endroit modifiable. Tout le reste est un lien ou un embed qui pointe vers cet endroit. Si vous êtes sur le point d'exporter un PNG pour le coller quelque part, demandez-vous si un lien suffirait. C'est généralement le cas.

2. Liez, ne copiez pas

Les wikis, sites de documentation et README doivent pointer vers le diagramme vivant, pas en contenir une image. Un diagramme intégré en direct change quand la source change ; une capture collée est fausse pour toujours après le changement suivant. Quand vous avez vraiment besoin d'une image statique, par exemple un PDF pour un auditeur, traitez-la comme un export daté et gardez-la hors de la documentation utilisée au quotidien.

3. Désignez un responsable

Chaque diagramme a un responsable : une personne, ou une équipe avec un interlocuteur nommé. Le responsable ne dessine pas chaque changement, mais c'est lui qui remarque quand le diagramme est faux et à qui l'on pose les questions. Indiquez le responsable sur le diagramme lui-même et dans votre index de diagrammes.

4. Rattachez les mises à jour à des événements existants

Ne comptez pas sur la mémoire. Associez les mises à jour de diagrammes à des événements qui ont déjà lieu :

• Pull requests. Ajoutez une case « impact sur l'architecture » au template de PR.
• ADR. Chaque architecture decision record accepté renvoie au diagramme qu'il modifie, et le diagramme est mis à jour dans le cadre de son acceptation.
• Postmortems d'incident. Si l'incident a montré que le diagramme était faux ou qu'il manquait une dépendance, sa correction devient une action de suivi.
• Revue trimestrielle. Les responsables consacrent quelques minutes à chaque diagramme pour vérifier qu'il correspond toujours à la réalité, puis mettent à jour la date de « dernière revue ».

Un extrait de template de PR :

## Architecture impact
- [ ] This change does not affect any architecture diagram
- [ ] I updated the affected diagram(s) and linked them below
- [ ] This needs an ADR (link):

5. Choisissez le bon niveau de détail

Utilisez des niveaux plutôt qu'une seule image géante. Le C4 model vous donne un vocabulaire commun : une vue System Context (personnes et systèmes), une vue Container (applications et stockages de données) et une vue Component à l'intérieur d'un container. Les niveaux supérieurs changent rarement et coûtent peu à maintenir. Les niveaux inférieurs changent souvent : ne les dessinez que là où les gens en ont besoin, et laissez le code faire foi en dessous.

Une règle utile : si un diagramme change à chaque sprint, il est probablement dessiné un niveau trop bas.

6. Rendez la date et la version visibles

Placez le responsable et une date de « dernière revue » dans un coin de chaque diagramme. Les lecteurs peuvent ainsi juger d'un coup d'œil de sa fiabilité : un diagramme revu le mois dernier et un autre revu il y a deux ans ne méritent pas la même confiance. Sans date, tous les diagrammes semblent avoir la même autorité, ce qui est pire que d'afficher une date ancienne.

7. Tenez un index des diagrammes

Une page liste tous les diagrammes qui comptent :

L'index rend les manques visibles (pas de responsable, date ancienne) et constitue le point de départ naturel de la revue trimestrielle.

8. Associez diagrammes et ADR

Un diagramme montre ce qu'est l'architecture. Il ne peut pas montrer pourquoi. Les architecture decision records comblent ce manque. Le format ADR d'origine de Michael Nygard est assez court pour que les gens en écrivent vraiment : titre, statut, contexte, décision, conséquences. Liez l'ADR depuis le diagramme et le diagramme depuis l'ADR :

# ADR-019: Move payment events to a dedicated queue

## Status
Accepted

## Context
Payment events share a queue with notifications.

## Decision
Give payment events their own queue.

## Consequences
One more queue to operate. Diagram "Payments: containers" updated.

Quand quelqu'un demande six mois plus tard « pourquoi est-ce comme ça ? », la réponse est à un clic.

Comment Archboard soutient un workflow de documentation vivante

Archboard est un espace de travail d'architecture hébergé, et l'essentiel du workflow ci-dessus correspond à des fonctionnalités existantes. Voici ce qui est couvert et là où vous avez encore besoin de votre propre processus.

• Une source de vérité. Chaque diagramme est un document unique dans votre workspace, avec sauvegarde automatique et snapshots de révision. Free conserve les 5 dernières révisions ; Pro conserve un an d'historique des révisions et Enterprise n'a pas de limite.
• Liez, ne copiez pas. Tous les plans ont des liens de partage publics (avec marque Archboard sur Free). Sur Pro et Enterprise, vous pouvez intégrer un diagramme dans votre site de documentation via iframe : la page affiche la version actuelle au lieu d'une capture qui dérive.
• Historique dans votre dépôt. Exportez le diagramme en JSON structuré et committez-le à côté du code ou de vos ADR. Vous obtenez un historique Git et une étape de revue pour les changements de diagramme, en plus des révisions dans l'application. L'export est une étape manuelle : intégrez-la à vos habitudes de PR.
• Des notes sur le canvas. Les nodes Markdown vivent sur le canvas : le responsable, la date de dernière revue, les liens vers les ADR et une courte légende sont dans le diagramme plutôt que dans un document séparé.
• Le bon niveau de détail. Le pack C4 Model propose les nodes Person, Software System, Container, Component et Database, ainsi que des boundaries. Les nodes sont des nodes à part entière avec des ports, et vous les reliez en connectant leurs ports. Gardez les vues context et container dans des diagrammes séparés.

Une mise en place concrète pour un système :

1. Créez deux diagrammes : « Payments: Context » et « Payments: Containers ».
2. Ajoutez en haut à gauche un node Markdown avec le responsable, la date de dernière revue et les liens vers les ADR concernés.
3. Sur Pro, intégrez la vue container dans la page de documentation du service. Sur Free, utilisez le lien de partage.
4. Quand une PR modifie l'architecture, mettez à jour le diagramme (ou laissez l'agent de code qui travaille sur la PR le faire via le serveur MCP d'Archboard), exportez le JSON et committez-le dans docs/architecture/ dans la même PR.
5. Ajoutez les deux diagrammes à votre page d'index.

Consultez la présentation du produit pour l'ensemble des fonctionnalités, le cas d'usage C4 pour les configurations propres à C4, et les tarifs pour le contenu de chaque plan. Free vous donne 3 diagrammes, chacun avec 15 nœuds de diagramme plus 150 notes, textes, autocollants et sujets de carte mentale, pour essayer une vue de contexte sur un système ; Pro débloque les diagrammes et nœuds illimités quand vous documentez toute la plateforme.

Checklist de la documentation vivante

• Chaque diagramme a exactement une source modifiable
• La documentation intègre ou lie le diagramme vivant, sans captures collées
• Chaque diagramme a un responsable nommé, indiqué sur le diagramme
• Le template de PR contient une case « impact sur l'architecture »
• Les ADR acceptés renvoient aux diagrammes qu'ils modifient
• Les postmortems demandent « le diagramme est-il toujours juste ? »
• Les responsables revoient leurs diagrammes chaque trimestre et mettent à jour la date
• Les diagrammes sont découpés par niveau C4, pas en une image géante
• Un index liste niveau, responsable, date de dernière revue et ADR
• La source du diagramme (par exemple un export JSON) est committée à côté du code

FAQ

Combien de diagrammes un système doit-il avoir ? Commencez par une vue context et une vue container. N'ajoutez des vues component que pour les parties sur lesquelles on vous interroge régulièrement. Quelques diagrammes exacts valent mieux que beaucoup de diagrammes périmés.

Les diagrammes doivent-ils vivre dans le dépôt ou dans un outil ? Modifiez-les à un seul endroit et conservez l'historique là où votre équipe revoit déjà les changements. Avec Archboard, vous modifiez sur le canvas et committez l'export JSON dans Git.

Commencez gratuitement — un siège, sans carte bancaire