Les diagrammes en code (diagrams as code) sont l'une des meilleures idées adoptées par l'ingénierie logicielle au cours de la dernière décennie. Un diagramme qui vit dans un fichier texte est un diagramme que l'on peut relire, comparer et restaurer. Il accompagne le code qu'il décrit, et il ne se perd jamais dans le dossier Téléchargements de quelqu'un.
Il y a un hic, et tous ceux qui ont maintenu un diagramme en code savent exactement lequel. Le texte est une merveilleuse façon de stocker un diagramme et une piètre façon de l'agencer. Dès que vous voulez décaler une seule boîte de deux centimètres vers la gauche, vous voilà de retour dans la syntaxe, à deviner des rangs, des directions et des règles de mise en page invisibles, à relancer le rendu jusqu'à ce que le moteur place enfin l'élément là où votre œil le voulait depuis le début.
Mermaid et D2 : le tableau blanc est la moitié manquante
Si l'on se tourne vers un tableau blanc, c'est parce qu'il répond à une autre question. Le code répond à « quelle est la source de vérité ». Un tableau blanc répond à « est-ce que ça a l'air juste ». Vous pointez une boîte et la faites glisser. Vous entourez en rouge le chemin risqué. Vous ne pensez pas à la façon dont la mise en page est encodée, car il n'y a pas d'encodage ; il y a juste l'image et votre main.
Le parti pris de LetDraw, c'est que vous ne devriez pas avoir à choisir. Collez le code de votre diagramme et il devient de vraies formes modifiables sur un canevas. Pas une image plate que l'on peut seulement regarder, mais de vraies boîtes et flèches que l'on peut saisir. Voici le type de source que la plupart des équipes conservent déjà dans un dépôt :
graph TD A[Client] --> B[API Gateway] B --> C[Auth Service] B --> D[Orders Service] D --> E[(Database)]
Importez ce Mermaid, et LetDraw ne vous en donne pas une image. Il vous donne le graphe sous forme de formes que vous pouvez déplacer :
La partie fastidieuse est terminée. Vous n'avez réglé aucune directive de mise en page. Vous avez obtenu un premier jet gratuitement, et tout ce qui est sur le canevas est à vous pour l'ajuster.
Déplacez une boîte, corrigez la note, mettez le chemin en évidence
Comme l'import produit de véritables formes, la moitié tableau blanc fonctionne tout simplement. Vous faites ce qui est pénible en texte et trivial à la main :
- Déplacez une boîte là où votre œil la veut, sans relancer le rendu pour vérifier
- Changez le style d'un nœud pour que celui qui compte se distingue des autres
- Ajoutez une note à côté de la partie sur laquelle les relecteurs posent toujours des questions
- Mettez un chemin en évidence pour montrer le flux de requêtes qui vous intéresse aujourd'hui
Les flèches vous aident au lieu de vous combattre. Les pointes de flèche natives de début et de fin sont intégrées, ainsi que les pointes creuses UML pour l'héritage et la cardinalité ER en patte d'oie pour le travail sur les schémas. Vous ne dessinez jamais un marqueur à la main et ne simulez jamais une notation avec un triangle pivoté. Et quand vous faites glisser une boîte par-dessus une autre, les connecteurs intelligents redirigent automatiquement la flèche autour de vos formes, pour que la ligne reste propre au lieu de traverser un nœud.
Le texte est l'endroit où un diagramme doit vivre. Un canevas est l'endroit où il doit être agencé. Vous ne devriez pas avoir à choisir.
L'aller-retour est tout l'intérêt
Voici ce qui rend la démarche honnête. Quand vous avez fini vos ajustements, vous exportez le dessin de nouveau en Mermaid ou D2. Le diagramme retourne dans votre dépôt sous forme de code, relisible dans une pull request comme n'importe quoi d'autre. La boucle ressemble à ceci :
- Le code dans votre dépôt est la source de vérité, comparé et relu
- Le canevas est l'endroit où un humain l'agence et le rend lisible
- Le code à nouveau à la sortie, pour que la mise en page améliorée soit livrée sous forme de texte
Cette dernière étape fait toute la différence entre « j'ai importé un diagramme une fois » et « des diagrammes en code qu'un humain supporte réellement de maintenir ». La syntaxe cesse d'être un mur. Vous gardez la relisibilité du code et l'ergonomie d'un tableau blanc, sans rien sacrifier de l'un ni de l'autre.
Comment l'essayer
Ouvrez un canevas, lancez Générer à partir du code et collez un extrait Mermaid ou D2 que vous avez déjà. Faites glisser les boîtes jusqu'à ce que le diagramme se lise comme vous le dessineriez sur un mur. Puis exportez-le de nouveau en code et déposez-le dans votre dépôt. Le trajet complet, du code au canevas puis au code, prend à peu près le temps qu'il vous a fallu pour lire ces lignes.