Wie man Software-Architekturdiagramme zeichnet (2022)

 (terrastruct.com)
3 Punkte von GN⁺ 2023-10-28 | 1 Kommentare | Auf WhatsApp teilen
  • Ein gutes Architekturdiagramm sorgt nicht durch Dekoration, sondern durch das richtige Abstraktionsniveau, Aktualität und die Beseitigung von Mehrdeutigkeiten dafür, dass Ideen vermittelt werden und die Zusammenarbeit langfristig erhalten bleibt.
  • Die Minimierung der Nachbarschaftsdistanz, also das Platzieren verbundener Elemente nahe beieinander, ist die Grundlage. Je größer ein Diagramm wird, desto eher muss man es wiederholt löschen und neu zeichnen.
  • Symmetrie erzeugt nicht nur einen angenehmen visuellen Eindruck, sondern verstärkt auch die Bedeutung, etwa indem Eingaben und Ausgaben auf unterschiedlichen Seiten platziert werden.
  • Wenn die Ausrichtung an Mittellinien beibehalten wird, wirken auch komplexe Konzepte weniger kompliziert, und beim Hinzufügen neuer Elemente gerät das Gesamtlayout nicht aus dem Gleichgewicht.
  • Container-Gruppen mit Beschriftung zeigen auf einen Blick Umgebungsgrenzen wie AWS und Azure, Abstraktionen wie ReaderWriter-Implementierungen oder Gruppen zusammengehöriger Objekte wie Cores.

Bedingungen für Diagramme, die Bestand haben

  • Gute Diagramme werden nach dem Ende eines Meetings nicht weggewischt, sondern können auch später noch als Bezugspunkt für Diskussionen und Fragen dienen.
  • Diagramme, die lange genutzt werden, haben einige gemeinsame Eigenschaften.
    • Die Elemente müssen auf dem richtigen Abstraktionsniveau liegen.
    • Sie müssen aktuell gehalten werden.
    • Sie dürfen keine Mehrdeutigkeiten enthalten.
  • Dieselben Entitäten und Beziehungen lassen sich auf viele Arten darstellen, aber manche Anordnungen unterstützen die Zusammenarbeit über die gesamte Projektdauer, während andere nach dem Meeting verschwinden.
  • Mit Schönheit ist hier nicht Dekoration wie Schatten oder abgerundete Ecken gemeint, sondern funktionale Schönheit, die Gedanken wirksam vermittelt.

Prinzipien für ein leicht lesbares Layout

  • Minimierung der Nachbarschaftsdistanz

    • Grundsätzlich sollten miteinander verbundene Knoten nahe beieinander gezeichnet werden.
    • Bei kleinen Diagrammen ist das einfach, aber je größer ein Diagramm wird und je mehr neue Verbindungen hinzukommen, desto leichter geht diese Eigenschaft verloren.
    • So wie man im Code beim Entdecken eines Edge Case den betroffenen Teil korrigiert oder in einem Dokument einen fehlenden Punkt durch Überarbeiten des Satzes ergänzt, sollte man auch ein Diagramm für die Dokumentation bei Bedarf löschen und neu zeichnen.
    • In Interviewsituationen kann der Aufwand des Neuzeichnens belastend sein, aber bei Dokumenten, die von mehreren Personen oder Teams genutzt werden, führen wiederholte Überarbeitungen zu einem besseren Diagramm.

  • Symmetrie finden

    • Symmetrie trägt stark zum ästhetischen Eindruck eines Diagramms bei, und das menschliche Gehirn neigt dazu, visuelle Symmetrie zu bevorzugen, ähnlich wie bei Gesichtern.
    • Selbst wenn alle Knoten ihren Nachbarn möglichst nahe sind, kann ein Mangel an Symmetrie das Diagramm wie eine leicht schiefe Zeichnung wirken lassen.
    • Auch wenn sich die Nachbarschaftsdistanz eines Knotens etwas vergrößert, kann die symmetrische Version besser aussehen.
    • Eingaben auf einer Seite und Ausgaben auf der anderen zu platzieren, stärkt zusammen mit der Symmetrie auch die Aussage des Diagramms.

  • Zentrierte Ausrichtung

    • Ausrichtung ist ein wichtiger Faktor dafür, dass ein Diagramm aufgeräumt wirkt.
    • Ein aufgeräumtes Diagramm macht Konzepte klarer, während ein unordentliches Diagramm Konzepte komplexer erscheinen lässt.
    • Wenn man auf einer leeren Fläche von Anfang an Formen zufällig platziert, bleibt oft auch die spätere Anordnung zufällig.
    • Ausrichtung ist nur zwischen zwei oder mehr Formen sinnvoll. Wenn man sie daher bei jedem neuen Element beibehält, wirkt das Diagramm ganz natürlich sauberer.
    • Oft ergibt sich Ausrichtung aus Symmetrie, aber nicht immer.

  • Container-Gruppen verwenden

    • Wenn ein Diagramm in mehrere beschriftete Bereiche unterteilt wird, kann die betrachtende Person die Struktur leichter verstehen.
    • Container können einem Diagramm die folgenden Informationen hinzufügen.
      • Sie ergänzen Kontext, etwa: „Diese Services befinden sich in AWS, und diese Services befinden sich in Azure.“
      • Sie zeigen Abstraktion, etwa: „Dies sind alles Implementierungen von ReaderWriter.“
      • Sie gruppieren zusammengehörige Objekte, etwa wenn core 1, 2, 3 und 4 in einem „Cores“-Container zusammengefasst werden.

Themen im nächsten Teil

  • In Teil 2 werden die folgenden Themen behandelt.
    • Zeichnen von Edge-Pfaden
    • Größe und Position von Labels
    • Farben
    • Icons

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2023-10-28
Hacker-News-Kommentare

  • Ich nutze D2 gern zum Erstellen von Diagrammen. Es ist ähnlich wie mermaid.js, bietet aber mehr Formatierungsoptionen, und persönlich finde ich auch die Syntax besser.
    Dazu habe ich auch einen kurzen Beitrag geschrieben: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • Ich finde, Diagramme sollten nicht hübsch sein. Farben zum Beispiel sollten nicht als ästhetische oder künstlerische Entscheidung eingesetzt werden, sondern zur Vermittlung von Bedeutung.
      Mir ist klar, dass hässliche Softwarediagramme nicht angenehm anzusehen sind, aber sie zu dekorieren ist ein bisschen wie Kurven in ein Liniendiagramm einzubauen. Es sieht visuell vielleicht besser aus, behindert aber die Daten, die vermittelt werden sollen.
    • Ich habe das Beispiel nachgebaut, und es war wirklich schick, wurde aber entgegen der Anleitung nicht von links nach rechts, sondern von oben nach unten gerendert.
      Ich habe das erste Beispiel x -> y als SVG gerendert und dann nur das SVG im Browser geöffnet; außerdem habe ich in der gesamten Dokumentation nach einer Möglichkeit gesucht, die Ausrichtung der Ausgabe festzulegen, aber nichts gefunden.
      Weil die Anleitung und das tatsächliche Ergebnis voneinander abwichen, habe ich die Nutzung abgebrochen. Mit der Suche nach "d2lang connection left to right" bin ich auf https://d2lang.com/tour/layouts/ gestoßen; es scheint aber nicht in der Übersichtsdokumentation verlinkt zu sein. Das zu ergänzen, dürfte Besuchern helfen.
    • https://flowchart.fun/ hat mir geholfen, sehr schnell Flowcharts zum Verstehen von Systemprozessen zu zeichnen. Am besten fand ich, dass es intuitiv ist und schnelle Iterationen erlaubt; auch das benutzerdefinierte CSS fürs Styling war ziemlich nützlich.
      Für Flowcharts halte ich es für eines der einfachsten und schnellsten textbasierten Diagramm-Tools, die ich bisher verwendet habe.
    • D2 hat mit tala eine sehr gute Layout-Engine, aber für die Nutzung braucht man eine kostenpflichtige Lizenz. Die beiden anderen Engines sind nicht ganz so gut.
    • Ich mag mermaid und nutze es häufig, aber D2 sollte ich mir auch ansehen. Deklarative Diagramme sind meiner Ansicht nach ein mächtiges Werkzeug, um Gedanken in leicht lesbarer Form festzuhalten und sie wie jeden anderen Text versionieren zu können.

  • Sobald sich ein System zu ändern beginnt, sind hübsche Diagramme sehr schwer zu pflegen. Man stelle sich vor, mitten in ein bereits komplexes Diagramm eine neue Box einzufügen; es kann eine Stunde dauern, alles wieder auszurichten.
    In den 2020ern ist die Zeit von Entwicklern wahrscheinlich besser dafür genutzt, Diagramme als Code zu verwalten: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • Ich scherze immer, dass 10 % der Diagrammerstellung darin bestehen, das eigentliche Diagramm zu bauen, und 90 % in der Ausrichtung der Pfeile.
      Aber ehrlich gesagt glaube ich, dass das kein Witz ist.
    • Ich habe ein C4-Modell gepflegt, um es in structurizr.com zu importieren und dort anzuzeigen, und ehrlich gesagt hat das keinen Spaß gemacht. Aus dem Code allein entstand nicht das intuitive Verständnis und der Gesamtüberblick, den man aus einem Diagramm bekommt, und es gab auch keine schnelle lokale Vorschau, sodass man den Code auf den Server hochladen musste.
      Noch schlimmer war, dass man beim Hinzufügen einer neuen Box normalerweise alle Pfeile neu ausrichten musste. Das Ergebnis war, dass die Diagramme nicht kontinuierlich aktuell blieben.
      Bei Sequenzdiagrammen war es besser, als ich plantML verwendet habe. Die Arbeit selbst war einfacher, sodass die Ausgabe des Interpreters meistens auch ohne manuelle Eingriffe brauchbar war.
    • Auch im Artikel wird angesprochen, dass das Ändern von Diagrammen viel Zeit kostet. In der Praxis stimmt das wirklich, und es wäre gut, wenn man einem standardisierten Schema sauber folgen könnte und das Tool Optionen für automatische Formatierung anböte.
    • Wenn man Elemente verschiebt und neu ausrichtet, muss man das ganze Diagramm wieder neu lernen. Wenn der frobnitz immer oben rechts war und dann plötzlich in die linke Mitte wandert, weil es für die Ausrichtung besser ist, mag das für jemanden, der es zum ersten Mal sieht, hilfreich sein; für jemanden, der sechs Monate darauf geschaut hat, wirkt es wie etwas völlig anderes.
      Das ist ähnlich wie bei einer hässlichen UI. Auch wenn sie hässlich ist, sind die Nutzer bereits daran gewöhnt. In dem Moment, in dem man sie „aufräumt“, zerstört man ihr mentales Modell und zwingt sie, es neu zu lernen.
    • Ob sich diese Zeitinvestition lohnt, hängt von Reichweite und Lebensdauer des Diagramms ab.
      Manchmal macht man nur eine Skizze, um Gedanken zu ordnen, die man 20 Minuten später wegwirft.
      Wenn es aber Referenzmaterial für Onboarding oder zur Erklärung eines Systems gegenüber anderen Teams ist, kann sich eine Stunde, die in etwas Verständlicheres investiert wird, durchaus auszahlen.

  • Für solche Dinge verwende ich yEd. Selbst wenn man Boxen und Pfeile komplett durcheinanderbringt, räumt es das mit ein paar Klicks im Menü automatisch auf.
    Allerdings muss man Kompromisse eingehen. Boxen in Boxen gehen nicht immer gut aus. Trotzdem kann ich damit viel schneller dokumentieren, und nach ein paar Versuchen bekommt man ein Gefühl dafür, was gut funktioniert und was nicht; für mich ist das ein guter Kompromiss.

    • Ich frage mich, ob yEd kostenlos nutzbar ist. Das zugrunde liegende yWorks SDK scheint selbst für einen einzelnen Entwickler auf einer einzigen Website einen fünfstelligen Betrag zu kosten. Wenn sie seit fast 20 Jahren Kunden haben, dürfte es ein ziemlich leistungsfähiges Tool sein.
    • Nutze ich genauso. Es gibt keinen Grund, das von Hand zu zeichnen.
      Man extrahiert die Beziehungen als TGF, importiert sie und wendet dann ein hierarchisches Layout an.
      Das Format from, to, relation reicht aus.
    • Aus ähnlichen Gründen verwende ich OmniGraffle.

  • Das hat starke Ähnlichkeiten mit elektrischen Schaltplänen, Schaltkreisdiagrammen und anderen technischen Zeichnungen. Es gibt nicht die eine „richtige“ Methode.
    Wie beim Code entscheidet die Fähigkeit, gute Abstraktionen und Darstellungsformen zu wählen, zwischen verständlichen Ideen und einem bedauerlichen Durcheinander. Es ist keine Frage von Schönheit oder Ästhetik, sondern ein Werkzeug, das aktives Denken und Arbeit am Design erfordert.

    • Das Abstraktionsniveau konsistent zu halten, ist manchmal wirklich schwer. Besonders bei Infrastrukturdiagrammen ist es schwierig, dem Drang zu widerstehen, weitere Details auf unterschiedlichen Ebenen einzufügen.
      Es wäre schön, ein Tool zu haben, mit dem man wie in einer Endlos-Zoom-Animation leicht in ein Diagramm hineinzoomen kann.

  • https://VisualFlows.io v1.0 soll bald veröffentlicht werden.
    In wenigen Minuten konnte eine animierte „Architektur“-Karte der SaaS der Muttergesellschaft erstellt werden: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    Die wichtigsten Funktionen sind Smart Sections, Smart Edges, Smart Node Deletion, Dark-/Light-Mode, Embeds, Drag & Drop für Bilder/SVG/GIFs, AWS-/Windows-/Google-Icons sowie Markdown, das nächste Woche kommen soll.
    Siehe Smart Sections: https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • Ich frage mich, warum man das statt des ausgereifteren https://whimsical.com mit derselben Ästhetik nutzen sollte.

  • Dieser Artikel hat mir wirklich gut gefallen. Wenn ich Architekturdiagramme zeichne, Dokumentation oder Code schreibe oder bei der Arbeit irgendetwas mache, nehme ich mir kurz Zeit, es „gut aussehen“ zu lassen.
    Warum genau, ist schwer zu erklären, aber ich weiß, dass es mir danach besser gefällt.
    Ich hatte ein wenig Sorge, dass das vielleicht nicht die beste Nutzung meiner Zeit ist, habe aber noch nie gehört, dass ich es lassen soll.
    Das Gute an diesem Artikel ist, dass er etwas, das ich eher nach Gefühl gemacht habe, als praktische Methode beschreibt, um etwas schöner zu machen.

    • Ich mache das auch so. Coden ist für mich eine ziemlich visuelle Tätigkeit. Ich kann es kaum anders als mit „Fluss“ beschreiben. Wenn Code keinen Fluss hat, bin ich nicht zufrieden.
      Es irritiert mich, wenn Teammitglieder offenbar kein visuelles Gespür für Code haben. Etwa wenn sie zwischen dem Ende einer Funktion und der nächsten Funktionsdeklaration keine Leerzeile lassen oder bei Funktionssignaturen mal einen Parameter pro Zeile schreiben und dann wieder mehrere in eine Zeile quetschen. Für mein Auge sticht das stark heraus, aber ihnen scheint es egal zu sein.
    • Selbst wenn man es mit niemandem teilt: Allein darüber nachzudenken, in welcher Reihenfolge Blöcke und Elemente auf der Seite stehen, bringt einen dazu, über die größere Struktur und die Abhängigkeiten nachzudenken. Das hilft enorm.
    • Beim Erstellen von Netzwerkdiagrammen in Visio habe ich dasselbe Gefühl. Ich gehe in den Steve-Jobs-Modus und fixiere mich auf kleine Details.
      Manchmal kostet es Zeit, aber es fühlt sich irgendwie erfüllend an. Ich weiß, dass ich ein gewisses technisches Kunsttalent habe, und in der Highschool wollte ich technischer Zeichner werden.
    • Genau dafür gibt es Markup. Es befreit einen von unproduktivem Aufhübschen. Gilt natürlich nicht fürs Coden.
    • „Die Diskussion kreist um dieses Diagramm. Menschen kommen beiläufig vorbei und schauen es sich an. Fragen werden beantwortet, indem man auf das Diagramm zeigt. Im Laufe des Tages drehen sich Stühle immer wieder zu diesem Mittelpunkt, und die Leute verschränken die Hände hinter dem Kopf.“
      Das ist das eigentliche Ziel von Visualisierung.

  • D2 eignet sich gut für solche Zwecke. In einer früheren Rolle habe ich ein Programm geschrieben, das alle serverless.yml-Dateien geparst und daraus automatisch ein riesiges D2-Diagramm erzeugt hat.
    Wir machten Microservices auf AWS, und es war praktisch, dass es sich automatisch aktualisierte, wenn das System wuchs. Ich hatte es so gebaut, dass man es in kleinere Diagramme je Subsystem aufteilen konnte, etwa anhand von SNS Topics.

    • draw.io mag ich ebenfalls.

  • Das erste Beispiel verstehe ich nicht. Der Autor spricht von einem ungeplanten Knoten, nennt ihn tatsächlich „I was unplanned“ und sagt dann „wenn ich es im Voraus geplant hätte“.
    Ich weiß nicht, wie man im Kontext eines Diagramms etwas Ungeplantes im Voraus planen kann. Ich frage mich, ob gemeint ist, dass man um alle Knoten herum genügend Leerraum lassen sollte.
    Außerdem lässt der vorgeschlagene Verbesserungsentwurf so wirken, als würden „something“ und „I was unplanned“ denselben Kanal oder Mechanismus verwenden, wenn sie mit „engine“ interagieren.

  • Ich nutze Miro; für Inhalte auf hoher Ebene oder Ideation ist es mit dem Post-it-Tool ziemlich gut. Über eine mittlere Detailebene hinaus kommt es aber nicht.
    Sobald Komponenten und Systeme feststehen, gibt es Werkzeuge, die für diese Arbeit besser geeignet sind.

  • Wenn die Projektdokumentation in Markdown vorliegt, kann man statt einer separaten Binärdatei einfach einen ```plantuml-Block einfügen, um ein Diagramm einzubetten.
    In GitLab wird das beim Anzeigen von .md-Dateien im Browser schön gerendert. GitHub hat diese Funktion noch nicht.