axelerator.de

Dynamische Diagramme

4 Minuten
#diagrams #visualization #documentation
15 November 2023

Statische Bilder, Videos und SVG-Animationen bringen jeweils ihre eigenen Herausforderungen mit sich, wenn es darum geht komplexe Systeme durch Diagramme zu visualisieren. Ich habe eine Minisprache und eine Webkomponente entwickelt, um Diagrammen ein erzählerisches Element hinzuzufügen.


Content:


Technische Dokumentation ist ein wesentlicher Bestandteil zur Erläuterung komplexer Systeme. Um die Beziehungen zwischen den Systemkomponenten effektiv darzustellen, sind Diagramme ein wesetnloches Wergzeug. Mit zunehmender Komplexität der Systeme wachsen jedoch auch die dazugehörigen Diagramme, was oft zu komplizierten und schwer verständlichen Darstellungen führt. Eine der größten Herausforderungen ist es zeitliche Abläufe verständlich abzubilden.

You can yog through the different states of the diagram using the arrow buttons ⬅ ➡ or the slider.
With the ✏️ button you can view and update the source of the diagram.

add "A" pos 0 -35 size 20 15 add "B" pos -35 5 size 20 15 add "C" pos 20 35 size 20 15 |- m1 -| connect "A" "B" "First" |- - -| connect "B" "C" "Second" |- closing the loop -| connect "C" "A" "Third" |- dance! -| update "C" pos 0 -35 update "A" pos -35 5 update "B" pos 20 35

Aktuellen Lösungsansätze und ihre Grenzen

Derzeit gibt es einige Ansätze, um diese Probleme zu lösen:

  1. Mehrere statische Bilder: Es ist üblich, sich entwickelnde Diagramme in mehrere statische Bilder aufzuteilen. Diese Methode kann jedoch umständlich sein, da sie den Leser zwingt, nach oben und unten zu scrollen, um auf die verschiedenen Stufen des Diagramms zu verweisen.

  2. Video-Format: Die Verwendung von Videos zur Animation von Diagrammen verleiht diesen einen dynamischen Aspekt, der es leichter macht, Veränderungen im Laufe der Zeit zu verstehen. Die Videoproduktion erfordert jedoch besondere Fähigkeiten und führt oft zu großen Dateien, was für eine schnell ladende Webdokumentation nicht ideal ist.

  3. SVG-Animationen: SVG, kombiniert mit CSS- und JS-Animationen, ist eine weitere Methode zur Erstellung dynamischer Diagramme. Dieser Ansatz ist zwar vielversprechend, erfordert aber vom Autor jedoch spezielle Fähigkeiten und potenziell teure Tools.

Eine neue, einfache Sprache für interaktive Diagramme

Ich persönlich war schon immer ein Fan von MermaidJS. Wie viele Entwickler schätze ich die Tatsache, dass textbasierte Diagrammgeneratoren einen Großteil der Komplexität wegnehmen, die mit visuellen Tools wie Inkscape oder diagrams.net verbunden ist.

Textbasierte tools wie MermaidJS, werden wegen ihrer Einfachheit und Effektivität sehr geschätzt. Der eigentliche Charme liegt in ihrer Fähigkeit, kurzen, prägnanten Text in ausgefeilte Diagramme zu verwandeln. Dieser textuelle Ansatz erleichtert nicht nur die Erstellung von Diagrammen, sondern lässt sich auch nahtlos in Versionskontrollsysteme integrieren, so dass eine klare Semantik über mehrere Übertragungen hinweg erhalten bleibt. Wenn deine Dokumentation in Form von Markdown Dokumenten bei Github liegt kannst du Diagramme direkt einbinden ohne weitere Werkzeuge zu benötigen.

Wenn ich ein Diagramm erstellen will, brauche ich meistens nur ein paar Kästchen, die durch Pfeile verbunden sind. Ich habe mich jedoch immer nach einer Möglichkeit gesehnt, mit meinen Diagrammen eine Geschichte zu erzählen, Ich möchte Elemente wie Kästchen und Pfeile gerne nach und nach einzuführen, anstatt alles auf einmal zu präsentieren. Das hat mich dazu veranlasst, eine neue Sprache und eine Webkomponente zu entwickeln, mit der genau das möglich ist. Mit meinem Tool kann ich meine Erzählung langsam aufbauen, indem ich dem Diagramm Schritt für Schritt Elemente hinzufüge und so die komplexen Informationen verständlicher und ansprechender machen kann.

Wenn du interaktive Diagramme auf deiner Seite haben möchtest lade die Webkomponente runter. Binde sie am Ende deiner Seite ein nachdem du die liquid-diagram Elemente speyifiziert hast.

<liquid-diagram style="display: block">
add "A"
  pos -10 -7
  size 20 15
add "B"
  pos -35 -35
  size 20 15
|- then -|
connect "A" "B" "A to B"
</liquid-diagram>

<script src="/assets/js/liquid-diagrams.js"></script>

add "client1" pos -30 -35 size 15 10 |- m1 -| add "load-balancer" pos -10 -5 size 25 10 add "app-server1" pos -30 15 size 25 10 add "app-server2" pos 20 15 size 25 10 add "db" pos -10 35 size 25 10 |- m2 -| connect "client1" "load-balancer" |- m3 -| connect "load-balancer" "app-server1" connect "app-server1" "db" |- m3 -| add "client2" pos 10 -35 size 15 10 |- m4 -| connect "client2" "load-balancer" connect "load-balancer" "app-server2" connect "app-server2" "db"