Le diagram-as-code résout le format du fichier, pas le problème de maintenance. Un diagramme textuel peut devenir obsolète, trompeur ou impossible à relire. Le workflow doit préciser son but, son responsable et les changements qui imposent une mise à jour.
Donner à chaque diagramme une décision à soutenir
Écrivez une phrase de but près de la source. « Montre les frontières de confiance de l’API publique » est vérifiable ; « architecture du système » est trop large. Utilisez un organigramme pour les décisions, une séquence pour l’ordre, un ER pour les relations et un Gantt pour un calendrier léger.
Stocker la source près de la documentation concernée
Un diagramme d’API doit rester près de sa documentation. Cette proximité facilite la responsabilité et la revue. N’exportez une image que si la plateforme ne rend pas Mermaid. Si la source et le SVG sont versionnés, indiquez lequel fait autorité et ne modifiez pas la sortie à la main.
Définir les déclencheurs de mise à jour
Une liste concrète comprend :
- Ajouter, retirer ou changer le propriétaire d’un service.
- Modifier une frontière de confiance ou une destination de données.
- Rendre un appel asynchrone ou ajouter une branche d’échec.
- Modifier optionalité ou cardinalité d’une relation.
- Changer un jalon de livraison documenté.
Relire le sens avant l’apparence
Vérifiez nœuds, relations, ordre et libellés avant layout et couleurs. Des petits changements, des ID stables et une instruction par ligne rendent les diffs lisibles. Séparez une reformatisation complète du changement sémantique.
Valider le moteur de publication
Les versions Mermaid et politiques de sécurité varient. Testez la syntaxe dans le moteur final et évitez HTML ou liens interactifs sous une politique stricte.
Utilisez l’éditeur Mermaid pour itérer et exporter, mais gardez la source versionnée et sa revue comme workflow durable.