Technische Diagramme, die Menschen verstehen
Kurz gesagt
Niveau: Fortgeschritten
Ein technisches Diagramm beantwortet eine Frage für ein Publikum. Es ist kein Porträt des ganzen Systems.
- Wähl die Art nach der Frage: Flussdiagramm für Entscheidungen, C4 auf einer Zoomstufe für Teile, Sequenzdiagramm für Reihenfolge und Zeit, Zustandsdiagramm für das Leben einer Bestellung, Datenflussdiagramm für personenbezogene Daten.
- Heb den kritischen Pfad hervor, beschrifte jeden Pfeil, nutz Formen einheitlich mit Legende, eine Detailstufe pro Diagramm.
- Zeichne von oben nach unten, damit es am Handy lesbar ist, und schreib eine Textbeschreibung für Screenreader.
- Verkettete Teile multiplizieren sich: Vier Teile mit je 99,9 % oder mehr lassen einen Checkout trotzdem rund 91 Minuten im Monat ausfallen.
- Halt Diagramme als Code neben dem System, damit sie sich mit ihm ändern.
Der Entwickler zeichnet Kästen voller Namen, die die Inhaberin nie gehört hat, die Inhaberin malt den Idealfall ohne jeden Fehler, und niemand weiß, wohin die Mailadresse der Kundin geht. Dieses Kapitel zeigt, welches Diagramm welche Frage beantwortet, wie du jedes zeichnest und welche Regeln jedes Diagramm lesbar machen, am Checkout eines erfundenen Innsbrucker Outdoorhändlers, gezeichnet für drei Zielgruppen.
Wie zeichnest du ein System so, dass alle es verstehen?
Jedes Unternehmen, das online verkauft, läuft auf einem System, das niemand sieht. Eine Kundin drückt auf "Bezahlen", und in anderthalb Sekunden passiert ein Dutzend Dinge: ein Blick ins Lager, eine Kartenprüfung, eine gespeicherte Bestellung, eine Mail in der Warteschlange, ein Paketschein, der auf den Druck wartet. Geht etwas schief oder muss sich etwas ändern, brauchen die Beteiligten ein Bild von diesem System. Und zwar dasselbe Bild, oder wenigstens Bilder, die sich nicht widersprechen.
Genau da hakt es meistens. Der Entwickler zeichnet Kästen voller Namen, die die Inhaberin nie gehört hat, die Inhaberin malt den Idealfall ohne jeden Fehler, und niemand weiß sicher, wohin die Mailadresse geht.
In diesem Kapitel geht es um technische Diagramme, die Menschen wirklich verstehen: welche Art von Diagramm welche Frage beantwortet, wie du jede zeichnest, und die paar Regeln, die jedes Diagramm lesbar machen, am Laptop, am Handy und im Screenreader. Falls du das erste Kapitel dieser Serie noch nicht kennst, warum ein Diagramm, und wann eine Tabelle besser ist, lohnt sich der Einstieg dort, denn die Grundregel gilt hier genauso: ein Bild, eine Botschaft.
Das Beispiel zieht sich durch den ganzen Text. Bergsteig Outdoor ist ein erfundener Händler für Outdoorausrüstung in Innsbruck, mit einem Onlineshop unter bergsteigoutdoor.example und einem Geschäft in der Altstadt. Theresa gehört das Geschäft, Lena macht die Analysen, und Florian betreut als Entwickler den Onlineshop. Alle Zahlen zu Bergsteig sind für das Beispiel erfunden.
Jedes Diagramm beantwortet eine Frage
Ein Diagramm ist keine Zeichnung "des Systems". Es ist die Antwort auf eine bestimmte Frage über das System. Ändert sich die Frage, brauchst du ein anderes Diagramm, obwohl sich am System nichts geändert hat.
Warum helfen Diagramme überhaupt? In einem viel zitierten Aufsatz haben die Kognitionsforscher Jill Larkin und Herbert Simon Diagramme mit Texten verglichen, die exakt dieselbe Information enthielten1. Ihr Ergebnis: Ein Diagramm hilft, wenn es Dinge, die zusammengehören, an dieselbe Stelle setzt. Dann findet man sie durch Hinschauen statt durch Suchen in Sätzen. Die Kehrseite steht im selben Aufsatz. Ein Diagramm, das nicht das Richtige zusammenrückt, ist nicht besser als Text, manchmal schlechter. Also kommt die Frage zuerst, denn die Frage entscheidet, was zusammengehört.
Fünf Fragen decken fast alles ab, was ein Unternehmen über seine Systeme wissen will:
- Was passiert Schritt für Schritt, und wo kann es schiefgehen? Ein Flussdiagramm.
- Was sind die großen Teile, und wie hängen sie zusammen? Ein Architekturdiagramm, zum Beispiel nach dem C4 Modell.
- Wer spricht mit wem, in welcher Reihenfolge, und wie lange dauert es? Ein Sequenzdiagramm.
- In welchen Zuständen kann eine Sache sein, und was bewegt sie dazwischen? Ein Zustandsdiagramm.
- Wohin fließen die Daten, vor allem personenbezogene? Ein Datenflussdiagramm.
Eine sechste Frage, "Was fällt aus, wenn dieser Teil ausfällt?", beantwortet ein Abhängigkeitsdiagramm. Oft ist das einfach ein Architekturdiagramm, mit anderen Augen gelesen.
Beispiel: drei Fragen zu einem Checkout
Theresa, Florian und Lena fragen in derselben Woche nach demselben Checkout.
Theresa fragt: "Wenn eine Karte abgelehnt wird, was sieht die Kundin, und ist die Bestellung dann weg?" Das ist eine Frage nach Schritten und Verzweigungen. Sie braucht ein Flussdiagramm.
Florian fragt: "Wenn wir den Paketdienst wechseln, welche Teile des Shops muss ich anfassen?" Das ist eine Frage nach Teilen und Verbindungen. Er braucht ein Architekturdiagramm.
Lena fragt im Auftrag von Theresa, die sich auch um den Datenschutz kümmert: "Welche fremden Firmen bekommen Name und Adresse einer Kundin?" Das ist eine Frage danach, wohin Daten fließen. Sie braucht ein Datenflussdiagramm.
Ein Checkout, drei Diagramme. Der Entscheidungsbaum unten ist dieselbe Überlegung, so aufgeschrieben, dass du sie auf deine eigenen Systeme anwenden kannst.
Flussdiagramme: Entscheidungen, Verzweigungen und der kritische Pfad
Ein Flussdiagramm zeigt einen Ablauf als Schritte und Entscheidungen in ihrer Reihenfolge. Es ist das älteste technische Diagramm und das einzige, das fast jeder ohne Vorwissen lesen kann. Für seine Symbole gibt es sogar eine internationale Norm, ISO 5807, erschienen 1985 und bis heute gültig2. Die Norm musst du nicht auswendig kennen, um ihre Kernidee zu nutzen: ein abgerundeter Kasten für Start und Ende, ein einfaches Rechteck für einen Schritt und eine Raute für eine Entscheidung, mit einem beschrifteten Pfeil pro Antwort.
Die Entscheidungen sind der eigentliche Punkt. Ein Flussdiagramm ohne Raute ist eine Liste, und eine Liste braucht kein Bild. Der Wert eines Flussdiagramms liegt darin, dass es zeigt, was auf jedem Zweig passiert, auch auf den unangenehmen: die abgelehnte Karte, der Artikel, der vor einer Sekunde ausverkauft war, die Adresse, die der Paketdienst nicht findet.
Die zweite nützliche Idee ist der kritische Pfad. In der Projektplanung ist das die längste Kette voneinander abhängiger Aufgaben, die bestimmt, wann das ganze Projekt fertig ist. James Kelley und Morgan Walker haben die Methode 1959 beschrieben, entwickelt an Ingenieurprojekten bei DuPont3. In Software hat der Begriff eine verwandte Bedeutung: die Kette von Schritten, die das Geld verdient und nie brechen darf, etwa Stöbern, Warenkorb, Bezahlen, Bestätigung. Dazu gibt es einen eigenen Artikel, der kritische Pfad in Software. Für Diagramme ist die Regel einfach: Zeichne jeden Zweig, und heb den kritischen Pfad hervor, damit das Auge ihm zuerst folgt.
Beispiel: der Checkout für die Inhaberin
Theresas Frage lautete: "Wenn eine Karte abgelehnt wird, was sieht die Kundin, und ist die Bestellung dann weg?" Florian zeichnet den Checkout auf der Ebene, die Theresa braucht. Keine Servernamen, keine Technik, nur was passiert und was die Kundin sieht.
Er beginnt beim Warenkorb und stellt die erste Entscheidung: Ist noch alles auf Lager? Wenn nicht, sieht die Kundin, welcher Artikel weg ist, und landet wieder im Warenkorb. Wenn ja, bezahlt sie. Die zweite Entscheidung: Gibt die Bank die Zahlung frei? Wenn nicht, sieht die Kundin eine klare Meldung und kann eine andere Karte nehmen. Der Warenkorb bleibt erhalten, die Bestellung geht nicht verloren. Wenn ja, wird die Bestellung gespeichert und eine Bestätigung verschickt.
Florian hebt den Pfad hervor, der das Geld verdient. Theresa sieht ihre Antwort auf einen Blick: Eine abgelehnte Karte führt zurück zum Bezahlen, der Warenkorb überlebt, und verloren ist nichts, solange die Kundin nicht aufgibt.
Das C4 Modell: vier Zoomstufen für Software
Das häufigste technische Diagramm ist die Kästchen und Pfeile Skizze "der Architektur". Es ist auch das am häufigsten nutzlose, weil es alles gleichzeitig mischt: die Kundin, eine Datenbanktabelle, einen Cloudanbieter, eine Bibliothek und einen Teamnamen, alle als Kästen derselben Form.
Das C4 Modell des Softwarearchitekten Simon Brown löst das, indem es vier Detailstufen trennt4. Stell dir den Zoom auf einer Landkarte vor.
- Kontext: dein System als ein einziger Kasten, mit den Menschen, die es nutzen, und den fremden Systemen, mit denen es spricht.
- Container: Du zoomst in dein System hinein. Ein Container ist hier alles, was für sich läuft oder Daten speichert: eine Webanwendung, eine Datenbank, ein Hintergrundprozess. (Das ist nicht dasselbe wie ein Docker Container, auch wenn einer darin laufen kann.)
- Komponenten: Du zoomst in einen Container und siehst seine Hauptteile.
- Code: Du zoomst in eine Komponente und siehst Klassen oder Funktionen.
Die C4 Seite ist dabei angenehm pragmatisch: Du brauchst nicht alle vier Stufen, nur die, die etwas bringen, und für die meisten Teams reichen Kontext und Container5. Jede Stufe passt zu einem anderen Publikum. Das Kontextdiagramm ist für alle, auch für die Inhaberin. Das Containerdiagramm ist für Entwickler und für alle, die das System einkaufen, betreiben oder absichern müssen.
Beispiel: der Checkout für den Entwickler
Florian' Frage war: "Wenn wir den Paketdienst wechseln, welche Teile muss ich anfassen?" Ein Kontextdiagramm ist dafür zu grob, ein Codediagramm viel zu fein. Er zeichnet die Containerebene.
Im Onlineshop von Bergsteig gibt es drei Container: die Webanwendung, die die Kundschaft sieht, die Datenbank mit den Bestellungen und einen Hintergrundprozess, der die langsamen Aufgaben erledigt (Mails verschicken, Paketscheine buchen), damit niemand darauf warten muss. Außerhalb liegen vier Systeme, die Bergsteig nicht gehören: der Zahlungsanbieter, der Maildienst, die Buchungsschnittstelle des Paketdienstes und das Warenwirtschaftssystem im Geschäft in der Altstadt.
Jeder Pfeil trägt eine Beschriftung, die sagt, was über ihn läuft. Jetzt ist Florian' Antwort sichtbar: Nur der Hintergrundprozess spricht mit dem Paketdienst. Ein Wechsel betrifft einen Container und einen Pfeil, nicht den Checkout selbst.
Sequenzdiagramme: wer mit wem spricht, und in welcher Reihenfolge
Ein Architekturdiagramm zeigt, wer mit wem sprechen kann. Ein Sequenzdiagramm zeigt, wer es bei einem bestimmten Ereignis tut, in zeitlicher Reihenfolge. Definiert ist es in der Unified Modeling Language (UML), der Standardnotation für Softwarediagramme, die die Object Management Group pflegt6: Jede beteiligte Stelle bekommt eine senkrechte Linie, die Zeit läuft nach unten, und jede Nachricht ist ein Pfeil von einer Linie zur anderen.
Achte auf die Richtung: Die Zeit läuft von oben nach unten. Damit ist ein Sequenzdiagramm von Natur aus handytauglich, und du kannst es als Ablauf von oben nach unten zeichnen, wenn gerade kein Sequenzwerkzeug zur Hand ist. Hauptsache, jeder Pfeil sagt, wer wem was schickt.
Sequenzdiagramme lohnen sich überall, wo ein fremder Dienst erst später antwortet, etwa bei Kartenzahlungen: Der Zahlungsanbieter bestätigt das Ergebnis oft in einer eigenen Nachricht, einem Webhook (der Anbieter ruft dein System von sich aus zurück). Außerdem machen sie Zeit sichtbar: Gib jedem Aufruf eine Dauer, und der langsame Schritt kann sich nicht mehr verstecken.
Beispiel: eine Kartenzahlung, Schritt für Schritt
Lena will wissen, warum sich der Checkout an manchen Tagen zäh anfühlt. Florian zeichnet die Kartenzahlung als Sequenz, von oben nach unten, ein Pfeil pro Nachricht.
Der Browser schickt die Bestellung an die Webanwendung. Die Anwendung fragt den Bestand in der Warenwirtschaft ab. Sie bittet den Zahlungsanbieter, die Zahlung einzuziehen. Der Anbieter antwortet "freigegeben" und bestätigt das später noch einmal per Webhook, und dieser Bestätigung vertraut der Shop. Die Anwendung speichert die Bestellung, legt die Bestätigungsmail in die Warteschlange des Hintergrundprozesses und zeigt der Kundin die Bestätigungsseite.
Es gibt einen echten Zweig: Kommt der Webhook nie an, fragt eine geplante Prüfung nach ein paar Minuten beim Anbieter den Status ab. So bleibt keine bezahlte Bestellung in der Schwebe.
Jetzt schreibt Florian zu jedem Schritt eine Dauer aus den Logdateien des Shops. Das passende Bild dafür ist ein Wasserfalldiagramm: Jeder Balken beginnt dort, wo der vorige endet. Die Länge eines Balkens ist die Zeit, die dieser Schritt hinzufügt, und der letzte Balken ist die Gesamtwartezeit der Kundin.
Das Bild beantwortet Lenas Frage. Von 1.680 Millisekunden gehen 1.400 auf das Konto des Zahlungsanbieters, rund 83 %. Der eigene Code von Bergsteig braucht 280 Millisekunden. Die Datenbank zu tunen würde die Summe kaum bewegen. Der sinnvolle nächste Schritt: die Antwortzeiten des Zahlungsanbieters an den zähen Tagen anschauen. Und weil die Mail nur eingereiht wird, lässt ein langsamer Maildienst niemanden warten. Das Sequenzdiagramm hat diese Designentscheidung sichtbar gemacht.
Zustandsdiagramme: das Leben einer Bestellung
Manches im Geschäft ist kein Ablauf, sondern ein Gegenstand, der sich mit der Zeit verändert. Die Bestellung ist das beste Beispiel. Sie wird angelegt, bezahlt, kommissioniert, gepackt, versendet, zugestellt, und manchmal storniert oder zurückgeschickt. Ein Zustandsdiagramm zeigt jeden Zustand, in dem die Sache sein kann, und jedes Ereignis, das sie in den nächsten bringt.
Die Idee geht auf die Statecharts von David Harel zurück, 1987 veröffentlicht, die Ingenieuren eine lesbare grafische Form für komplexes Verhalten gaben7. Die UML führt sie als Zustandsautomaten6. Die volle Notation brauchst du nicht. Zwei Regeln tragen den größten Teil: Jeder Zustand ist ein Kasten, und jeder Pfeil trägt das Ereignis, das den Wechsel auslöst. Auch die Pfeile, die du nicht zeichnest, zählen. Gibt es keinen Pfeil von "versendet" zurück zu "bezahlt", darf das System diesen Wechsel nicht zulassen, und ein Entwickler kann genau das testen.
Beispiel: eine Bestellung vom Warenkorb bis zur Haustür
Florian und Theresa zeichnen das Leben einer Bergsteig Bestellung gemeinsam. Eine Bestellung beginnt als "wartet auf Zahlung". Scheitert die Zahlung oder bricht die Kundin ab, wird sie nach einer Stunde storniert. Klappt die Zahlung, ist sie "bezahlt". Dann sucht jemand im Lager die Artikel zusammen ("in Kommissionierung") und packt sie ("gepackt"). Der Paketdienst holt das Paket ab ("versendet") und stellt es zu ("zugestellt"). Innerhalb der Rückgabefrist kann die Kundin eine zugestellte Bestellung zurückgeben, und sobald das Paket zurück ist, wird erstattet.
Beim Zeichnen fällt Theresa etwas auf, das der Code erlaubt hat: Eine Kundin konnte eine schon gepackte Bestellung stornieren, und im Lager hat es niemand erfahren. Die beiden legen eine neue Regel fest: Ab "gepackt" wird aus einer Stornierung eine Rücksendung, und das passt.
Ein Zustandsdiagramm sagt Lena auch, welche Zahlen auf das Betriebsdashboard gehören: wie viele Bestellungen gerade in welchem Zustand stecken. Ein Zustand, der vollläuft, während der nächste leer bleibt, ist eine Warteschlange, die stillsteht.
An einem normalen Morgen ist der Balken "gepackt" klein, weil Paketscheine automatisch gebucht werden und der Paketdienst zweimal am Tag kommt. 31 gepackte Bestellungen heißen: Die Buchung beim Paketdienst ist ausgefallen. Das Containerdiagramm von vorhin sagt Florian genau, wo er suchen muss: beim Hintergrundprozess und seinem Pfeil zum Paketdienst.
Datenflussdiagramme: wohin personenbezogene Daten fließen
Ein Datenflussdiagramm folgt den Daten statt dem Ablauf. Es kennt vier Arten von Elementen: externe Stellen (Menschen oder Organisationen außerhalb deines Systems, etwa die Kundin oder der Paketdienst), Prozesse (alles, was Daten verarbeitet, etwa "Bestellung annehmen"), Datenspeicher (wo Daten liegen, etwa die Bestelldatenbank) und Datenflüsse (die Pfeile, jeweils beschriftet mit den Daten, die fließen). Sicherheitsteams nutzen dieselben Diagramme für die Bedrohungsanalyse und zeichnen zusätzlich Vertrauensgrenzen ein, also die Stellen, an denen Daten von einer verantwortlichen Stelle zur nächsten wechseln, weil dort Angriffe besonders gern ansetzen8.
Für ein Unternehmen ist der dringendste Einsatz der Datenschutz. Nach Artikel 30 der Datenschutz Grundverordnung (DSGVO) führt jede verantwortliche Stelle ein schriftliches Verzeichnis von Verarbeitungstätigkeiten: welche personenbezogenen Daten sie verarbeitet, wozu, über wen, wer sie bekommt, ob sie in Drittländer gehen, wie lange sie gespeichert bleiben und wie sie geschützt sind9. Für Unternehmen mit weniger als 250 Beschäftigten gibt es eine Ausnahme, aber die Wirtschaftskammer Österreich (WKO) stellt klar, dass sie nur greift, wenn alle Bedingungen erfüllt sind, unter anderem, dass die Verarbeitung nur gelegentlich erfolgt10. Ein Onlineshop verarbeitet Kundendaten jeden Tag. Ein Datenflussdiagramm ist der schnellste Weg, das Verzeichnis richtig aufzubauen.
Das Gesetz verlangt ein Verzeichnis, kein Bild, aber im Bild fällt ein Datenfluss, den niemand aufgeschrieben hat, am schnellsten auf. Kartenzahlungen liefern einen zweiten Grund. Der Sicherheitsstandard der Kartenbranche, PCI DSS in Version 4.0.1, verlangt in Anforderung 1.2.4 ein korrektes Datenflussdiagramm, das alle Flüsse von Kartendaten über Systeme und Netze zeigt und bei Änderungen der Umgebung aktualisiert wird11.
Beispiel: der Checkout für den Datenschutz
Lenas Frage für Theresa war: "Welche fremden Firmen bekommen Name und Adresse einer Kundin?" Lena und Florian gehen eine Bestellung durch und notieren jede Stelle, an die ein personenbezogenes Datum fließt.
Die Kundin gibt Name, Mailadresse, Lieferadresse und Kartendaten ein. Die Kartendaten gehen direkt aus ihrem Browser in das Zahlungsformular des Zahlungsanbieters und berühren die Server von Bergsteig nie. Alles andere landet in der Bestelldatenbank. Von dort geht die Mailadresse an den Maildienst für die Bestellbestätigung. Name, Adresse und Telefonnummer gehen an den Paketdienst für die Zustellung. Das Analysetool bekommt nur eine pseudonyme Besucherkennung, und nur, wenn die Kundin im Cookiebanner zugestimmt hat. Die Buchhaltungssoftware bekommt den Namen und die Rechnung.
Aus dem Diagramm baut Lena eine kleine Bestandsaufnahme: wie viele einzelne personenbezogene Angaben jedes System hält. So wird aus dem Bild die Zeilenliste für das Verzeichnis, eine Zeile pro Empfänger.
Theresa hat ihre Antwort: Drei fremde Firmen bekommen Name oder Adresse (der Zahlungsanbieter mit der Rechnungsadresse, der Paketdienst, die Buchhaltungssoftware), eine vierte bekommt die Mailadresse. Das Analysetool bekommt nur eine pseudonyme Kennung, und nur mit Einwilligung. Auch das zählt als personenbezogenes Datum und bekommt eine eigene Zeile. Jeder Empfänger wird eine Zeile im Verzeichnis, mit Zweck und Speicherdauer.
Abhängigkeitsdiagramme: was ausfällt, wenn ein Teil ausfällt
Jeder Pfeil in einem Architekturdiagramm ist auch eine Abhängigkeit. Ist der Zahlungsanbieter down, ist der Checkout down, egal wie gesund die eigenen Server von Bergsteig sind. Ein Abhängigkeitsdiagramm liest die Architektur genau mit dieser Frage: Welche Teile müssen alle laufen, damit der kritische Pfad läuft?
Die Mathematik dahinter ist kurz und überraschend. Die Site Reliability Engineers von Google formulieren die Regel so: Ein Dienst kann nicht verfügbarer sein als die Schnittmenge all seiner kritischen Abhängigkeiten12. Fallen die Teile unabhängig voneinander aus, ist die Verfügbarkeit einer Kette das Produkt der Verfügbarkeiten ihrer Teile:
Dabei ist der Anteil der Zeit, in der der ganze kritische Pfad funktioniert, der Anteil der Zeit, in der Teil funktioniert (zum Beispiel für 99,9 %), die Zahl der Teile, von denen der Pfad abhängt, und heißt "alle miteinander multiplizieren". Das Multiplizieren stimmt, weil bei unabhängigen Ereignissen die Wahrscheinlichkeit, dass alle eintreten, das Produkt der Einzelwahrscheinlichkeiten ist: siehe Grundlagen: Wahrscheinlichkeit.
Verfügbarkeiten in Prozent sind schwer zu fühlen. Ausfallminuten nicht. Für einen Monat mit 30 Tagen, also Minuten, gilt:
Dabei ist die erwartete Ausfallzeit in Minuten pro Monat, die Verfügbarkeit als Anteil zwischen und und die Zahl der Minuten im Monat. Das ist eine Quote, umgerechnet in eine Anzahl, siehe Grundlagen: Verhältnisse und Raten.
Beispiel: vier Teile, die einzeln gut aussehen
Der Checkout von Bergsteig hängt an vier Teilen: der Webanwendung (99,95 % verfügbar), der Datenbank (99,99 %), der Warenwirtschaft im Geschäft (99,9 %) und dem Zahlungsanbieter (99,95 %). Die Werte sind für das Beispiel erfunden.
Schritt eins, multiplizieren:
Der Checkout als Ganzes funktioniert also rund der Zeit, weniger als jedes einzelne Teil (Grundlagen: Wahrscheinlichkeit erklärt, warum verkettete Chancen schrumpfen).
Schritt zwei, in Minuten umrechnen:
Das sind Minuten im Monat, in denen niemand bezahlen kann, gegenüber 43 Minuten beim schwächsten Einzelteil (der Schritt von der Quote zur Anzahl steht in Grundlagen: Verhältnisse und Raten).
Jetzt schau dir an, wie man dieselben Zahlen zeigen kann. Das erste Diagramm ist das, was in Statusberichten meistens auftaucht: Verfügbarkeit je Teil, auf einer Achse von 0 bis 100 %. Jeder Balken sieht voll aus. Alles wirkt in Ordnung.
Die ehrliche Fassung zeigt dieselben Daten als Ausfallminuten im Monat und ergänzt den Balken, auf den es ankommt: den ganzen Pfad.
Das zweite Diagramm stößt ein nützliches Gespräch an. Die Warenwirtschaft im Geschäft steuert fast die Hälfte der Ausfallzeit bei. Muss der Checkout wirklich auf sie warten? Hielte die Webanwendung eine eigene Kopie der Bestände, alle paar Minuten aufgefrischt, fiele die Warenwirtschaft vom kritischen Pfad, und die Kette verlöre ihr schwächstes Glied. Das Abhängigkeitsdiagramm hat diese Möglichkeit sichtbar gemacht. Ein Diagramm mit Prozentwerten hat sie versteckt.
Die Regeln, die jedes Diagramm lesbar machen
Egal welche Art: Dieselben wenigen Regeln entscheiden, ob ein Diagramm verstanden oder höflich übergangen wird. Die beste Grundlage dafür ist die Arbeit von Daniel Moody zu grafischen Notationen in der Softwaretechnik. Er hat Prinzipien für Notationen aufgestellt, die das Gehirn schnell und genau verarbeiten kann, darunter eine eindeutige Zuordnung von Symbolen zu Bedeutungen (semiotische Klarheit), Symbole, die sich leicht unterscheiden lassen (wahrnehmbare Unterscheidbarkeit), das Zerlegen komplexer Diagramme in handliche Teile (Komplexitätsmanagement) und die Verbindung von Grafik und Text (duale Kodierung)13. Die Notations Checkliste des C4 Modells macht aus ähnlichen Ideen eine praktische Liste: ein Titel, eine Legende und eine Beschriftung an jeder Linie14.
Eine Detailstufe pro Diagramm
Alles in ein Bild zu packen skaliert nicht, weil die möglichen Verbindungen zwischen Kästen viel schneller wachsen als die Kästen selbst. Bei Kästen ist die Zahl der Paare, die ein Pfeil verbinden könnte:
Dabei ist die Zahl der möglichen Verbindungen und die Zahl der Kästen. Stell dir ein Raster mit je einer Zeile und einer Spalte pro Kasten vor: Jede Zelle ist ein Paar, und die Formel zählt die Zellen oberhalb der Diagonale, jedes Paar einmal und keinen Kasten mit sich selbst. Siehe Grundlagen: Matrizen.
Beispiel: von sechs auf fünfzehn Kästen
Das Containerdiagramm von Florian hat 8 Elemente. Theresa wollte einmal "alles auf einer Seite": die Container, dazu die Hauptkomponenten der Webanwendung, dazu die Scanner im Lager und die Kassa im Geschäft. Das macht 15 Kästen.
Sechs Kästen erlauben mögliche Verbindungen. Fünfzehn Kästen erlauben . Wer das Bild verstehen will, muss jetzt siebenmal so viele mögliche Beziehungen prüfen.
Also lässt Florian das Containerdiagramm, wie es ist, und zeichnet die Komponenten der Webanwendung als zweites Diagramm, vom ersten aus verlinkt. Zwei klare Bilder schlagen ein dichtes.
Gleiche Formen und eine Legende
Eine Form sollte überall dasselbe bedeuten, in jedem Diagramm der Sammlung. Ist ein abgerundeter Kasten auf der einen Seite "fremdes System" und auf der nächsten "Datenbank", muss man die Zeichnung jedes Mal neu lernen. Und weil keine Notation allen bekannt ist, sagt eine kurze Legende an jedem Diagramm, was Formen und Linienarten bedeuten14.
Beispiel: der gestrichelte Kasten
In den Diagrammen von Bergsteig heißt ein gestrichelter Kasten immer: "ein System, das Bergsteig nicht gehört". Der Zahlungsanbieter, der Maildienst, der Paketdienst, die Warenwirtschaft im Geschäft. Eine Raute ist immer eine Entscheidung. Ein hervorgehobener Pfad ist immer der kritische Pfad. Die Legende unter jedem Diagramm sagt das in je einer Zeile. Sieht Theresa irgendwo einen gestrichelten Kasten, weiß sie sofort: Hier hilft ein Anruf beim Lieferanten, kein Auftrag an Florian.
Eine Beschriftung an jedem Pfeil
Ein unbeschrifteter Pfeil ist das Versprechen, dass alle richtig raten. Das tun sie nicht. Die C4 Checkliste verlangt für jede Linie eine Beschriftung, die zur Richtung passt, und warnt vor vagen Einzelwörtern wie "nutzt"14. Eine gute Beschriftung sagt, was fließt, und für Entwickler auch, wie.
Beispiel: von "nutzt" zu einer echten Beschriftung
In einem älteren Diagramm von Bergsteig stand am Pfeil von der Webanwendung zum Zahlungsanbieter nur "nutzt". Florian ersetzt das durch "Zahlungsanfrage, HTTPS" und ergänzt einen zweiten Pfeil zurück vom Anbieter zur Webanwendung: "Zahlung bestätigt, Webhook". Auf den zweiten Pfeil kam es an. Er fehlte im alten Diagramm ganz, und deshalb hatte niemand darüber nachgedacht, was passiert, wenn er ausbleibt.
Von oben nach unten, fürs Handy und für Screenreader
Diagramme werden am Handy gelesen, in einem Chatverlauf oder zwischen zwei Terminen. Ein breites Diagramm, das von links nach rechts läuft, schrumpft auf einem schmalen Bildschirm zu unlesbarem Text. Ein Diagramm von oben nach unten behält seine Schriftgröße und wird einfach gescrollt. Jedes Diagramm auf dieser Website läuft genau deshalb von oben nach unten, lässt sich in einer Vollbildansicht öffnen und hat eine Textbeschreibung für Screenreader.
Diese Beschreibung ist kein netter Zusatz. Ein Screenreader kann keinen Pfeilen folgen. Die Beschreibung muss der Reihe nach sagen, was das Diagramm zeigt und wo es sich verzweigt, damit jemand, der es nicht sieht, dieselbe Antwort bekommt wie jemand, der es sieht. Kapitel 11 dieser Serie, barrierefreie Diagramme, geht ins Detail.
Beispiel: die Beschreibung des Checkout Flussdiagramms
Florian schreibt die Beschreibung für Theresas Flussdiagramm so, als würde er es ihr am Telefon vorlesen: "Die Kundin prüft den Warenkorb. Ist ein Artikel ausverkauft, sieht sie welcher und kehrt zum Warenkorb zurück. Sonst bezahlt sie mit Karte. Lehnt die Bank ab, sieht sie eine klare Meldung, behält ihren Warenkorb und kann eine andere Karte nehmen. Gibt die Bank frei, wird die Bestellung gespeichert, und sie sieht die Bestätigung." Fünf Sätze, jeder Zweig, kein "siehe den Kasten links". Ist die Beschreibung schwer zu schreiben, will das Diagramm meistens zu viel auf einmal.
Diagramme als Code, damit sie wahr bleiben
Ein Diagramm, das letztes Jahr stimmte, ist heute eine Gefahr, weil man ihm immer noch glaubt. Diagramme veralten aus einem einfachen Grund: Sie leben woanders. Der Code ändert sich im Repository, die Zeichnung liegt in einer Präsentation oder auf einem Whiteboardfoto, und niemand pflegt beides.
Die Lösung: Diagramme als Textdateien neben dem Code ablegen, damit eine Änderung am System und die Änderung an seinem Diagramm im selben Pull Request ankommen (dem Änderungsvorschlag, den eine Kollegin prüft, bevor er übernommen wird). Mehrere etablierte Werkzeuge arbeiten so, hier fair nach ihrer eigenen Dokumentation beschrieben:
- Mermaid macht aus einer kurzen Textbeschreibung Flussdiagramme, Sequenzdiagramme, Zustandsdiagramme und mehr15. GitHub stellt Mermaid Blöcke direkt in Markdown Dateien, Issues und Pull Requests dar16.
- PlantUML zeichnet UML Diagramme, auch Sequenz und Zustandsdiagramme, aus reinem Text17.
- Structurizr, ebenfalls von Simon Brown, beschreibt ein C4 Modell einmal in einer eigenen Sprache und erzeugt daraus die Diagramme für jede Zoomstufe18.
- Graphviz ist die bewährte Open Source Engine, die Kästen und Pfeile aus einer Textbeschreibung anordnet, und viele andere Werkzeuge nutzen sie im Hintergrund19.
Das Werkzeug ist weniger wichtig als die Gewohnheit: Das Diagramm liegt im Repository, wird wie Code geprüft, und eine Änderung, die einen Pfeil verschiebt, ohne das Diagramm anzupassen, geht zurück.
Beispiel: ein Paketdienstwechsel in einem Pull Request
Bergsteig wechselt den Paketdienst. Der Pull Request von Florian ändert den Buchungscode im Hintergrundprozess und im selben Zug eine Zeile in der Modelldatei, aus der das Containerdiagramm entsteht. Das Modell in der Sprache von Structurizr sieht so aus:
workspace {
model {
kundin = person "Kundin"
shop = softwareSystem "Onlineshop Bergsteig"
zahlung = softwareSystem "Zahlungsanbieter"
paket = softwareSystem "Neuer Paketdienst, Buchungsschnittstelle"
kundin -> shop "Stöbert und bestellt"
shop -> zahlung "Schickt Zahlungsanfragen an"
shop -> paket "Bucht Paketscheine bei"
}
views {
systemContext shop {
include *
autoLayout tb
}
}
}
Zwei Details zählen für diesen Artikel. Jede Beziehung trägt eine Beschreibung, also bekommt jeder Pfeil eine Beschriftung. Und autoLayout tb sagt Structurizr, das Diagramm von oben nach unten anzuordnen18. Als Lena den Pull Request prüft, sieht sie den alten Paketdienst im selben Schritt aus dem Diagramm verschwinden, in dem er aus dem Code verschwindet, und sie aktualisiert noch am selben Nachmittag das Verzeichnis von Verarbeitungstätigkeiten, weil sich auch das Datenflussdiagramm geändert hat.
Ein Checkout, drei Zielgruppen: die Mappe
Zusammengenommen beschreibt eine kleine Mappe von Diagrammen den Checkout von Bergsteig. Keines davon ist "das" Diagramm. Jedes beantwortet eine Frage für ein Publikum, und sie passen zusammen, weil sie aus demselben Gang durch dasselbe System entstanden sind.
| Zielgruppe | Ihre Frage | Diagramm | Detailstufe |
|---|---|---|---|
| Theresa, Inhaberin | Was sieht die Kundin, wenn es schiefgeht? | Flussdiagramm mit kritischem Pfad | Schritte und Entscheidungen, keine Technik |
| Theresa, Inhaberin | Was passiert mit einer Bestellung über ihr Leben? | Zustandsdiagramm | Zustände und die Ereignisse dazwischen |
| Florian, Entwickler | Welche Teile sprechen mit welchen? | C4 Containerdiagramm | Anwendungen, Datenbanken, fremde Systeme |
| Florian, Entwickler | In welcher Reihenfolge, und wie lange dauert jeder Schritt? | Sequenzdiagramm plus Wasserfalldiagramm | Eine Zahlung, Nachricht für Nachricht |
| Theresa und Lena, Datenschutz | Wer bekommt welche personenbezogenen Daten? | Datenflussdiagramm | Angaben, Systeme, Empfänger |
| Alle | Was fällt aus, wenn ein Teil ausfällt? | Abhängigkeitssicht auf das Containerdiagramm | Kritische Teile und ihre Verfügbarkeit |
Fazit
Ein technisches Diagramm ist eine Antwort, kein Porträt. Fang bei Frage und Publikum an, wähl die passende Art, heb den kritischen Pfad hervor, bleib bei einer Detailstufe, beschrifte jeden Pfeil, zeichne von oben nach unten und schreib die Beschreibung, die ein Screenreader vorliest. Dann leg die Diagramme neben den Code, damit sie sich mit dem System ändern.
Nichts davon ist Dekoration. Jedes Diagramm in der Mappe von Bergsteig hat zu einer Entscheidung geführt: eine Stornoregel, eine Stelle zum Suchen, wenn sich Bestellungen stauen, eine Warenwirtschaft, die vom kritischen Pfad fliegt, ein Verzeichnis von Verarbeitungstätigkeiten, das der Wirklichkeit entspricht. Das ist der Test für jedes Diagramm, das du zeichnest: Weiß jemand nach dem Lesen, was zu tun ist?