Diagramme als Code mit Mermaid: was gut funktioniert und wo die Grenzen liegen

Worum es geht

Mermaid (zitiert) ist ein JavaScript-basiertes Werkzeug, das an Markdown angelehnte Textdefinitionen in Diagramme rendert: Flussdiagramme, Sequenzdiagramme, Klassen- und Zustandsdiagramme, Entity-Relationship-Diagramme, Gantt-Diagramme und mehr. Die Dokumentation beschreibt den Zweck damit, der Dokumentation zu helfen, mit der Entwicklung Schritt zu halten, und bezeichnet Dokumentations-Verfall (doc-rot) als ein Catch-22, das Mermaid mitlösen hilft. GitHub (zitiert) rendert einen Fenced Code Block mit der Sprachkennung mermaid in Markdown-Dateien, Issues und Pull Requests als Diagramm; andere Wikis und Static-Site-Generatoren binden dieselbe Bibliothek ein.

Warum es wichtig ist

Ein als Bild gespeichertes Diagramm wird in einem Werkzeug bearbeitet, das niemand im Team mehr besitzt, und das Review zeigt nur eine binäre Änderung. Ein als Text gespeichertes Diagramm liegt neben dem Code, den es beschreibt, wird im selben Pull Request geändert, und sein Diff zeigt, welcher Pfeil sich verschoben hat. Genau diese Eigenschaft hält Architekturskizzen, Zustandsautomaten und Anfrageflüsse aktuell.

So wird es angewendet

• Ein Diagramm pro Fragestellung ("was ruft während des Checkouts was auf") behalten, mit höchstens einem Dutzend Knoten; lieber aufteilen als wachsen lassen.
• Den zur Aussage passenden Diagrammtyp verwenden: Sequenzdiagramme für geordnete Interaktionen, Zustandsdiagramme für Lebenszyklen, Flussdiagramme für Entscheidungen, ER-Diagramme für Daten.
• Beschriftungen mit Satzzeichen in Anführungszeichen setzen und reservierte Wörter als Knotenkennungen vermeiden; Parse-Fehler sind der häufigste Fehlerfall.
• accTitle und accDescr (zitiert) ergänzen, damit das gerenderte SVG einen barrierefreien Titel und eine Beschreibung für Screenreader und für Agenten trägt, die die Seite als Text lesen.
• Das Diagramm in das Dokument einbetten, das es erklärt, nicht in einen separaten Diagrammordner, und im Text erwähnen, was die Leserin oder der Leser sehen soll.
• Die Mermaid-Version im eigenen Site-Build fixieren; prüfen, ob die Plattformen, auf denen veröffentlicht wird, die verwendeten Diagrammtypen rendern.

Stolpersteine

Das Layout ist automatisch; Richtung und Gruppierung lassen sich andeuten, aber Knoten nicht präzise platzieren, und ein Diagramm, das exakte Platzierung braucht, gehört in ein anderes Werkzeug. Grosse Diagramme werden unleserlich und langsam. Das Rendering hängt von der Mermaid-Version ab, die der Viewer einbindet, sodass ein Diagramm auf einer Plattform rendert und auf einer anderen scheitert. Viewer, die die Bibliothek nicht ausführen (einfaches Git-Hosting, E-Mail, manche PDF-Pipelines), zeigen den Quelltext; diesen für sich allein lesbar halten. Ein Diagramm ist weiterhin eine Aussage über das System und verfällt wie Prosa, wenn es nicht zusammen mit dem Code, den es beschreibt, überprüft wird.