Willkommen – hier gibt’s konkrete Hilfe.

Fangen wir gleich mal mit dem schlimmstmöglichen Fall an, einem “Diagramm-des-Grauens” (danke übrigens an Markus Harrer für die Erfindung dieses Namens). So wie nachstehend dürfen Ihre Diagramme auf keinen Fall aussehen – es sei denn, Sie sind beruflich in der Sabotage tätig.

Abb. 1: Diagramm des Grauens (untauglich, völlig unbrauchbar, miserabel)
Abb. 1: Diagramm des Grauens (untauglich, völlig unbrauchbar, miserabel)

Das ist in hohem Maße missverständlich und verwirrend – aber schauen wir genauer hin:

Im Folgenden sehen wir uns Schritt für Schritt an, wie wir zu besseren Diagrammen kommen. Falls Sie mal nachlesen möchten, wie Sie insgesamt zu besserer Dokumentation kommen, empfehle ich Ihnen (Disclaimer: meinen) grundlegenden Artikel zu den Principles of technical documentation

Ich verwende ein paar Begriffe aus dem arc42-Universum. Bei Unklarheiten schauen Sie in der arc42-Dokumentation nach.

Ein einziger Zweck

Tipp 1: Ein Diagramm sollte einen einzigen Zweck erfüllen, eine einzige Art von Information vermitteln.

Anders formuliert: Jedes Diagramm sollte dem Separation of Concerns Prinzip genügen.

Formulieren Sie (explizit) das Ziel eines Diagramms: Welche Information soll es vermitteln, welche Tatsache erläutern, welchen Zweck erfüllen? Diese Formulierung sollte in der Regel ohne das Wort und auskommen.

Beispiele:

Erklärte Bedeutung von Symbolen

Tipp 2: Erklären Sie die Bedeutung aller verwendeten Symbole (genauer: der Typen von Symbolen) in einer Legende. Die sollte erklären, was die Kästen und Linien Ihres Diagramms repräsentieren.

Repräsentiert ein Kasten im Diagramm ein Stück Quellcode, eine Instanz davon zur Laufzeit, einen (echten oder virtuellen) Computer? Repräsentiert er die Planung oder die Realität? Bei den Linien oder Pfeilen wird’s noch schlimmer: Bedeutet eine Linie einen Aufruf oder eine Benachrichtigung? Synchron oder asynchron? Zeigt sie einen Daten- oder Kontrollfluss? Ohne Erklärung können Betrachter:innen nur raten, oder die Bedeutung nach eigenem Ermessen auslegen.

Tipp 3: Verwende eine etablierte Notation, sofern passend.

Standardisierte Notationen, wie etwa UML oder SysML, spielen hier einen Vorteil aus: Zu denen gibt es ein (OK, ziemlich sperriges) Metamodell, das die Bedeutung aller grafischen Elemente exakt beschreibt. Leider sind diese beiden relativ kompliziert, und bieten aus meiner Sicht zu viele Diagrammtypen an. Die Einschränkung “sofern passend” im Tipp bezieht sich genau darauf: Nutzen Sie diese Standards nur dann, wenn Ihre Stakeholder diese Notationen auch verstehen.

Sie können auch ohne UML prima Diagramme erstellen, sofern Sie Ihre Kästen und Linien erklären.

Ausdrücklich erklärte Bedeutung von Elementen

Tipp 4: Erklären Sie die verwendeten Namen (Bezeichner) in Ihren Diagrammen, am besten als Tabelle.

Im nachfolgenden Beispiel habe ich Tipp 1 bereits berücksichtigt. Dennoch bleibt völlig unklar, was hier die Bedeutung der Begriffe “Reporter” oder “Checker” sind.

Abb. 2: Legende allein genügt nicht
Abb. 2: Legende allein genügt nicht

Da hilft eine Tabelle weiter, in der die Bedeutung dieser Elemente erklärt ist:

Element Verantwortlichkeit / Bedeutung
Checker führt die HTML-Prüfungen durch und identifiziert strukturelle Probleme. Stützt sich dabei auf die Fehlerbehandlung von Parser
Parser Open-Source Bibliothek zum Parsen von HTML-Dateien (https://jsoup.org)
Suggester Schlägt Abhilfen für die Probleme vor, die vom Checker gefunden wurden
Reporter Erzeugt ein formatiertes Ergebnisdokument mit allen identifizierten Problemen

Konsistente Benennung von Elementen

Auch über einzelne Diagramme hinweg sollten Sie gleiche Elemente auch gleich benennen – und verschiedene Dinge sollten verschiedene Bezeichnungen tragen.

Insbesondere sollte der Zusammenhang zu Code oder technischen Details durch konsistente Benennung ersichtlich werden: Wählen Sie beispielsweise Komponenten- oder Paketnamen in statischen Diagrammen identisch zu den entsprechenden Konstrukten im Sourcecode. Niemals auf Englisch programmieren, aber Diagramme dann mit deutschen Bezeichnern, das verwirrt.

Sparsame Verwendung von Details

Tipp 5: Verzichten Sie auf Details.

Verzichten Sie speziell auf solche Details, die Sie einfacher im Text erklären können, oder die sich häufig ändern.

Abb. 3: Viele versus weniger Details (Auszug)
Abb. 3: Viele versus weniger Details (Auszug)

In der obigen Abbildung verwende ich eine (abstrahierte) Schnittstellen (reportError), statt alle einzelnen Detailschnittstellen der Reporter-Komponente im Diagramm aufzuzählen.

Besonders gilt dieser Tipp für Sequenz- oder andere Laufzeitdiagramme, bei denen die Notation nahezu beliebige Details ermöglicht: Die Sequenzdiagramme der UML schlagen vor, Abläufe auf der Ebene einzelner Objektinstanzen (sprich: das niedrigste mögliche Abstraktionsniveau) zu beschreiben. Ich halte das in den meisten Fällen für übertrieben, und würde stattdessen Abläufe auf höherer Abstraktionsebene beschreiben wollen.

Sie könnten große, detaillierte Sequenzen auf mehrere kleinere, übersichtliche Diagramme verteilen. Siehe dazu nachfolgendes Beispiel (bei dem ich wissentlich im schlechten Teil auf die Lesbarkeit ohne Hilfsmittel, siehe unten, verzichte).

Im Zweifel teilen Sie ein detailliertes, umfangreiches Diagramm lieber auf mehrere kleine auf, wie im folgenden Beispiel gezeigt:

Abb 4: Detailliertes Sequenzdiagramm versus gröberes Sequenzdiagramm
Abb 4: Detailliertes Sequenzdiagramm versus gröberes Sequenzdiagramm

Ein Dutzend Elemente

Tipp 6: Beschränken Sie Ihre Diagramme auf circa ein Dutzend Elemente (Kästchen) und die dafür notwendigen Beziehungen (Linien).

Zwar kommt aus der Psychologie die 7 ± 2 Regel (Millersche Zahl), aber meiner Erfahrung nach verstehen Menschen auch ein paar mehr Symbole in Diagrammen. Ihre Stakeholder sollen Ihre Diagramme ja nicht auswendig lernen, sondern deren Inhalt verstehen.

Ich möchte dieses “circa ein Dutzend” für verschiedene Diagrammarten konkretisieren:

Falls Sie mehr Elemente haben, dann können Sie über Zusammenfassung (Clusterung, Abstraktion) die Menge der jeweils gezeigten Elemente reduzieren, und zusätzlich verfeinernde Detaildiagramme erstellen (oder die Details im Text erklären).

Sparsamer und konsistenter visueller Stil

Tipp 7: Verwenden Sie visuelle Stilelemente (etwa: Farben, Linienstil, Pfeilspitzen, Schattierungen, Icons) sparsam und konsistent.

Beschränken Sie sich auf möglichst wenige verschiedene Stilelemente. Behalten Sie diesen Stil im Diagramm durchgängig bei. Ideal ist es, wenn Sie auch über Diagramme hinweg an einem konsistenten Stil festhalten.

Nachfolgend ein schlechtes und besseres Beispiel (zur Vereinfachung habe ich dabei die Legende weggelassen).

Abb. 5: Schlechter und besserer visueller Stil
Abb. 5: Schlechter und besserer visueller Stil

Wichtige Dinge im Zentrum

Tipp 8: Positionieren Sie die wesentlichen Elemente eines Diagramms möglichst zentral.

Ein schönes Beispiel dafür sind die typischen Kontextdiagramme. Typischerweise (und das ist gut so!) finden Sie darin das System in der Mitte, und die externen Nachbarsysteme rund herum platziert. Stellen Sie sich vor, das wäre anders… siehe nachfolgende Abbildung:

Abb. 6: Schlechtes und besseres Kontextdiagramm
Abb. 6: Schlechtes und besseres Kontextdiagramm

Lesbare Beschriftungen

Tipp 9: Verwenden Sie ausreichend große Beschriftungen.

Kaum ein Stakeholder möchte Ihre Diagramme mit einem Mikroskop lesen müssen. In meiner beruflichen Realität bin ich immer wieder mit Diagrammen konfrontiert (ja, in diesen Fällen muss ich ausdrücklich von Konfrontation sprechen) gewesen, deren Beschriftungen ohne Hilfsmittel wie Lupen nicht mehr lesbar waren.

Teilweise konnten die Autor:innen das durch die verwendeten Werkzeuge erklären (was das Resultat leider nicht verbessert hat): Die Diagramme sind ursprünglich in z. B. UML- oder Grafikwerkzeugen auf 30-Zoll Monitoren gestaltet worden, in der finalen Dokumentation aber auf weniger als 20 cm schmale Druckseiten komprimiert worden.

Bitte denken Sie beim Layout und der Dimensionierung von Diagrammen an die Ausgabeformate. Jedes Diagramm sollte ohne Hilfsmittel auf einer A4-Seite im Querformat lesbar sein.

Gutes Layout

Über Geschmack können wir bekanntlich streiten, aber zu gutem Layout haben sich einige Grundregeln etabliert (die nur Gurus außer Kraft setzen sollten).

Tipp 10: Beachten Sie die Grundregeln guten Layouts [1]

Layout kann Ihre Diagramme ansehnlich machen, sodass Stakeholder sie mit Freude betrachten. Alternativ kann schlechtes Layout dazu führen, dass Menschen die vermittelten Informationen nicht erkennen oder sich mit dem Inhalt eines solchen Diagramms nicht auseinandersetzen wollen.

(Möglichst) keine Kreuzungen von Linien

Tipp 11: Vermeiden Sie Kreuzungen von Linien.

Vergleichen Sie in folgendem Beispiel die linke und rechte Version: Die Kreuzungen der linken Seite machen das Diagramm meiner Ansicht nach deutlich schlechter lesbar (und damit schwerer verständlich).

Abb. 7: Linien-Kreuzungen
Abb. 7: Linien-Kreuzungen

Wenn Sie die Elemente Ihres Diagramms nicht kreuzungsfrei positioniert bekommen, lassen Sie Kreuzungen explizit anzeigen, wie im folgenden Beispiel gezeigt:

Abb. 8: Wenn Kreuzungen, dann gut sichtbar.
Abb. 8: Wenn Kreuzungen, dann gut sichtbar.

Quellen

Erstaunlich wenige Blogs oder Artikel setzen sich mit gutem Stil von Diagrammen auseinander.

  1. Hierzu bietet das Internet eine Vielzahl von Quellen an. Mir hat die kurze Zusammenfassung von Farah Radzi (10 principles of visual designs) gut gefallen, ebenso die von Kelley Gordon (5 Principles of Visual Design).  ↩

  2. Das ist sowohl ernst gemeint als auch ein Insider–Witz. Hallo Robert.  ↩

Fazit

Mit den Tipps aus diesem Artikel können Sie Ihre bestehenden Diagramme schrittweise verbessern, in Richtung Verständlichkeit, Wartbarkeit und damit auch bessere Akzeptanz. Dennoch bleiben inhaltlich wertvolle Architekturdiagramme trotz aller Tipps und Ratschläge eine anspruchsvolle Aufgabe: Gehen Sie iterativ vor, beschaffen Sie sich Feedback und verbessern Sie schrittweise.

TAGS