Mermaid machte Diagramme-als-Code salonfähig: Sequenzdiagramme wurden zu Text in Markdown

UML war der große Versuch der Softwarewelt, Entwurfsdiagramme zu standardisieren: Die OMG nahm es 1997 an, und die ISO übernahm es 2005. Es brach unter seinem eigenen Gewicht zusammen – die UML-2.2-Dokumentation umfasste über 1.000 Seiten, und der Standard wurde an schwere CASE-Tools und aufwendige Vorarbeit gebunden, sodass sich in den 2020er-Jahren Befürworter und Gegner gleichermaßen einig waren, dass er im Wesentlichen tot war.

Ein Artefakt überlebte ihn: das Sequenzdiagramm, eine einfache Karte der zwischen Komponenten fließenden Nachrichten. Seine Anhänger konnten es zeichnen, doch die Werkzeuge machten es mühsam – jessems, ein Entwickler bei BitHawk, fand das Ziehen von Formen in Lucidchart langsam und brüchig, wobei jede künftige Änderung das Layout zerstörte.

Der Schritt war Mermaid, eine JavaScript-Bibliothek, in der man das Diagramm als reinen Text deklariert: Teilnehmer, Pfeile und Nachrichten, geschrieben innerhalb eines Markdown-Codeblocks, gerendert von der Markdown-Toolchain. Der Autor probierte es aus in der Erwartung, dass sich Code-auf-Code falsch anfühlen würde, und fand es dann schnell, schmerzlos und schön; er begann, Sequenzdiagramme in die Umsetzungspläne seiner User Stories einzubetten, sie mit Hot Reload in der Vorschau zu betrachten und als Bilder zu exportieren, um sie in HTML-Felder einzufügen.

Warum es sich durchsetzte, liegt daran, dass das Diagramm zu einem gewöhnlichen Code-Artefakt wurde. Es lebt neben der Story, die es dokumentiert, wird im Code-Review gediffed, wird in einer einzeiligen Änderung statt durch eine Neuanfertigung aktualisiert und wird überall gerendert, wo Markdown gerendert wird – GitHub-Markdown unterstützt Mermaid von Haus aus, wie Kommentatoren im Hacker-News-Thread anmerkten. Mermaids Gründer fasste es als informelle Einfachheit auf, die die starre Komplexität der Werkzeuge aus der Rational-Rose-Ära ersetzte.

Das Diagramm zu einem Code-Artefakt machen: es als Text in Markdown tippen und den Renderer es zeichnen lassen

Ein Diagramm zu tippen ist schneller, als eines zu ziehen, sodass die Erstellungskosten von einer Sitzung am Canvas auf ein paar Zeilen neben dem Dokument sinken.

Text lässt sich wie Code versionieren und diffen, sodass eine Diagrammaktualisierung eine einzeilige Änderung im Review ist statt einer fragilen Neuanfertigung.

Markdown-Renderer gibt es bereits überall, sodass das Diagramm dort angezeigt wird, wo das Team ohnehin Dokumente liest und kommentiert.

UML starb durch hinzugefügte Komplexität; Mermaid behielt nur das nützliche Artefakt und entfernte die Werkzeugkosten darum herum.

Ein Standard überlebt, indem er die Kosten dort senkt, wo die Leute ohnehin arbeiten: Das Diagramm, das gewinnt, ist dasjenige, das man in ein Dokument tippen und im Review diffen kann.

Der Beitrag erzielte am 24. Juli 2023 auf Hacker News 207 Punkte und 111 Kommentare. Kommentatoren merkten an, dass GitHub-Markdown Mermaid von Haus aus rendert, verglichen es mit PlantUML, d2 und Graphviz und empfahlen Markdown-Ökosysteme wie Docusaurus, die es mit einem einzigen Installationsbefehl rendern. Der Autor behielt den Workflow bei BitHawk bei und entwarf Umsetzungspläne, deren Sequenzdiagramme in Markdown-Dateien leben, wobei mermaid-cli sie als Bilder exportierte, wenn Aufzeichnungen HTML erforderten.