Mermaid a fait tenir les diagrammes-as-code : les diagrammes de séquence sont devenus du texte dans Markdown

UML fut la grande tentative du logiciel pour normaliser les diagrammes de conception : l'OMG l'a accepté en 1997 et l'ISO l'a adopté en 2005. Elle s'est effondrée sous son propre poids — la documentation d'UML 2.2 dépassait 1 000 pages et la norme s'est retrouvée liée à de lourds outils CASE et à un travail préparatoire pesant, si bien que dans les années 2020, partisans comme détracteurs s'accordaient à la considérer comme essentiellement morte.

Un artefact lui a survécu : le diagramme de séquence, une simple carte des messages circulant entre composants. Ses survivants pouvaient le dessiner, mais l'outillage rendait la chose pénible — jessems, un développeur chez BitHawk, trouvait le glisser-déposer de formes dans Lucidchart lent et fragile, la moindre modification future ruinant la mise en page.

La solution fut Mermaid, une bibliothèque JavaScript où l'on déclare le diagramme en texte brut : participants, flèches et messages écrits dans un bloc de code Markdown, rendus par la chaîne d'outils Markdown. L'auteur l'a essayé en s'attendant à ce que du code sur du code paraisse incongru, puis l'a trouvé rapide, indolore et beau ; il a commencé à intégrer des diagrammes de séquence dans les plans de mise en œuvre de ses user stories, les prévisualisant avec le rechargement à chaud et les exportant en images à coller dans des champs HTML.

Ce qui a fait tenir la chose, c'est que le diagramme est devenu un artefact de code ordinaire. Il vit à côté de la story qu'il documente, se compare en revue de code, se met à jour par une modification d'une ligne au lieu d'un redessin, et s'affiche partout où Markdown s'affiche — le Markdown de GitHub prend en charge Mermaid nativement, l'ont fait remarquer des commentateurs du fil Hacker News. Le fondateur de Mermaid l'a présenté comme une simplicité informelle remplaçant la complexité rigide des outils de l'époque de Rational Rose.

Faire du diagramme un artefact de code : le taper en texte dans Markdown et laisser le moteur de rendu le dessiner

Taper un diagramme est plus rapide que le glisser, si bien que le coût de rédaction passe d'une session sur canevas à quelques lignes à côté du document.

Le texte se versionne et se compare comme du code, si bien qu'une mise à jour de diagramme est une modification d'une ligne en revue au lieu d'un redessin fragile.

Les moteurs de rendu Markdown existent déjà partout, si bien que le diagramme s'affiche là où l'équipe lit déjà les documents et les commente.

UML est mort en ajoutant de la complexité ; Mermaid n'a gardé que l'artefact utile et a supprimé le coût d'outillage qui l'entourait.

Une norme survit en réduisant le coût là où les gens travaillent déjà : le diagramme qui gagne est celui que l'on peut taper dans un document et comparer en revue.

Le billet a recueilli 207 points et 111 commentaires sur Hacker News le 24 juillet 2023. Des commentateurs ont noté que le Markdown de GitHub affiche Mermaid nativement, l'ont comparé à PlantUML, d2 et Graphviz, et ont recommandé des écosystèmes Markdown comme Docusaurus qui l'affichent avec une seule commande d'installation. L'auteur a conservé le flux de travail chez BitHawk, rédigeant des plans de mise en œuvre dont les diagrammes de séquence vivent dans des fichiers Markdown, mermaid-cli les exportant en images lorsque les enregistrements exigeaient du HTML.