Diagram as Code löst das Dateiformat-, nicht das Wartungsproblem. Auch ein Textdiagramm kann veraltet oder unprüfbar werden. Der Workflow muss Zweck, Verantwortung und Änderungen definieren, die eine Aktualisierung verlangen.
Jedes Diagramm unterstützt eine Entscheidung
Notieren Sie den Zweck neben der Quelle. „Zeigt Vertrauensgrenzen der öffentlichen API“ ist prüfbar; „Systemarchitektur“ ist zu breit. Flussdiagramme erklären Entscheidungen, Sequenzdiagramme Reihenfolgen, ER-Diagramme Datenbeziehungen und Gantt-Diagramme einfache Zeitpläne.
Quelle nahe der relevanten Dokumentation speichern
Ein API-Diagramm gehört zur API-Dokumentation. Nähe verbessert Eigentümerschaft und Review. Exportieren Sie nur dann ein Bild, wenn die Plattform Mermaid nicht rendern kann. Werden Quelle und SVG eingecheckt, muss klar sein, welche Datei maßgeblich ist; generierte Ausgaben werden nicht von Hand geändert.
Aktualisierungsauslöser definieren
Eine konkrete Checkliste umfasst:
- Service hinzufügen, entfernen oder einem anderen Team zuordnen.
- Vertrauensgrenze oder Datenziel ändern.
- Einen API-Aufruf asynchron machen oder einen Fehlerzweig ergänzen.
- Optionalität oder Kardinalität einer Beziehung ändern.
- Einen dokumentierten Liefermeilenstein ändern.
Bedeutung vor Aussehen prüfen
Knoten, Beziehungen, Reihenfolge und Beschriftungen müssen zuerst stimmen. Kleine Änderungen, stabile IDs und eine Anweisung pro Zeile erleichtern Diffs. Trennen Sie großflächige Formatierung von semantischen Änderungen.
Publikationslaufzeit validieren
Mermaid-Versionen und Sicherheitsregeln unterscheiden sich. Testen Sie neue Syntax im Zielrenderer und vermeiden Sie HTML oder interaktive Links bei strikten Richtlinien.
Der Mermaid-Editor unterstützt lokale Iteration und Export; dauerhaft maßgeblich bleiben eingecheckte Quelle und Projekt-Review.