Zum Inhalt springen
btk.io

Field Notes · 5 Min.

Zuletzt geprüft: 6. Oktober 2026

Inhalt · 6 Abschnitte

Field Note: Komplexität im System verstecken, nicht in der Dokumentation

Eine einfache Oberfläche ist keine einfache Architektur

Ich möchte, dass Menschen ein digitales System benutzen können, ohne zuerst verstehen zu müssen, wie es gebaut ist. Die Oberfläche soll ihnen zeigen, was sie tun können und was als Nächstes passiert. Datenmodelle, Schnittstellen, Regeln und technische Abhängigkeiten müssen dafür nicht sichtbar sein.

Das heißt aber nicht, dass ich Komplexität verschwinden lassen will. Sie lässt sich nicht wegdesignen. Sie wandert nur an einen anderen Ort: in die Architektur, in den Betrieb und in die Entscheidungen, die das System zusammenhalten.

Dort muss sie lesbar bleiben. Für mich ist das der Unterschied zwischen einem System, das nach außen einfach wirkt, und einem System, das tatsächlich undurchschaubar geworden ist.

Was Nutzer nicht wissen müssen

Wer ein System benutzt, sollte nicht mit seiner internen Struktur belastet werden. Die Person muss nicht wissen, welche Komponente Daten bereitstellt oder wie viele Schritte hinter einer Funktion liegen. Sie muss zuverlässig erkennen können, was ihre Eingabe bewirkt, welche Auswahl möglich ist und ob eine Aktion abgeschlossen wurde.

Das ist keine Einladung, wichtige Informationen zu verbergen. Es ist eine Frage der passenden Ebene. Eine verständliche Oberfläche reduziert die Zahl der Dinge, über die jemand gleichzeitig nachdenken muss. Sie macht Entscheidungen greifbar, statt interne Mechanik offenzulegen.

Auch im redaktionellen Bereich gilt das. Ein gutes Inhaltsmodell muss nicht als technische Tabelle vor der Redaktion liegen. Aber die Felder, Begriffe und Beziehungen darin müssen so gestaltet sein, dass die Redaktion sinnvoll damit arbeiten kann. Wenn das Modell nicht zu den tatsächlichen Aufgaben passt, wird die technische Komplexität irgendwann in den Arbeitsablauf durchgereicht.

Was ich zuerst prüfe: Muss diese Komplexität für die Person sichtbar sein, damit sie eine gute Entscheidung treffen kann? Wenn nicht, gehört sie wahrscheinlich nicht in die Oberfläche. Das beantwortet aber noch nicht, wie sie intern verständlich bleibt.

Was nicht verschwinden darf

Die interne Komplexität muss für diejenigen nachvollziehbar sein, die das System verändern und betreiben. Dazu gehören nicht nur der Aufbau und die verwendeten Werkzeuge. Ebenso wichtig sind die Grenzen des Systems: Woher kommen Daten? Welche Komponente darf sie verändern? Welche Annahmen stecken in einem Ablauf? Was muss geprüft werden, bevor eine Änderung live geht?

Wenn diese Fragen unbeantwortet bleiben, ist die Komplexität nicht vereinfacht. Sie ist nur in das Gedächtnis einzelner Personen verschoben worden. Das kann eine Zeit lang funktionieren. Es macht es aber schwerer, Änderungen zu beurteilen, Fehler einzugrenzen oder Verantwortung zu übernehmen.

Komplexität dokumentieren heißt für mich deshalb nicht, jede technische Einzelheit aufzuschreiben. Es heißt, die Zusammenhänge festzuhalten, die für Betrieb und Veränderung wichtig sind. Eine Dokumentation soll nicht beeindrucken, sondern jemandem helfen, die nächste sinnvolle Entscheidung zu treffen.

Bei einem gewachsenen WordPress-System kann das zum Beispiel bedeuten, Inhalte, Rollen, Schnittstellen und Plugins nicht als voneinander unabhängige Liste zu betrachten. Entscheidend ist, wie sie zusammenwirken und welche Aufgabe sie erfüllen. Dazu passt auch der Gedanke, Datenmodelle statt Plugin-Stapel in den Mittelpunkt zu stellen: Datenmodelle statt Plugins.

Dokumentation ist eine zweite Oberfläche

Ich denke über Dokumentation gern als über eine zweite Oberfläche nach. Die erste richtet sich an Menschen, die das Produkt benutzen. Die zweite richtet sich an Menschen, die seinen Zustand verstehen, es verändern und den Betrieb sichern müssen.

Beide sollten die passende Information in der passenden Form anbieten. Die erste Oberfläche erklärt nicht, wie die Datenbank aufgebaut ist. Die zweite sollte nicht so tun, als gäbe es keine Nutzeraufgaben, redaktionellen Abläufe oder Produktentscheidungen. Technik und Nutzung sind keine getrennten Welten. Die Dokumentation muss zeigen, wo sie sich berühren.

Dazu gehören mindestens drei Arten von Wissen: Was ist vorhanden? Warum ist es so gestaltet? Und wie lässt sich eine Änderung sicher durchführen? Eine reine Komponentenliste beantwortet meist nur die erste Frage. Ohne die anderen beiden kann sie schnell veralten oder missverstanden werden.

Eine gute Übergabe setzt für mich an derselben Stelle an: Nicht möglichst viel Material übergeben, sondern den nächsten Menschen in die Lage versetzen, das System zu verstehen und weiterzuführen. Mehr dazu steht in Was eine gute Übergabe enthält.

Änderungen müssen nachvollziehbar bleiben

Je mehr Teile zusammenwirken, desto wichtiger wird es, Änderungen nicht als isolierte Handgriffe zu behandeln. Ich orientiere mich dabei an Know → Change → Prove: erst den Zustand erfassen, dann eine Änderung nach Vorschau und Freigabe ausführen und anschließend ihre Wirkung belegen.

Das ist auch das Leitprinzip meiner Engine Room, einer eigenen Plugin-Suite für spezialisierte Aufgaben. Der wichtige Punkt ist für mich nicht die Zahl der Werkzeuge. Es ist die Trennung zwischen Verstehen, Verändern und Prüfen. So muss nicht jede Person alle internen Mechanismen kennen. Aber die Änderung bleibt für Entwicklung und Betrieb nachvollziehbar.

Dokumentation kann diese Schritte unterstützen. Sie hält fest, welcher Zustand relevant ist, welche Entscheidung getroffen wurde und woran sich erkennen lässt, ob die Änderung funktioniert. Sie ersetzt weder Tests noch sorgfältige Umsetzung. Sie macht aber sichtbar, worauf sich diese Prüfungen beziehen.

Ich versuche deshalb, Dokumentation nicht erst am Ende eines Projekts als Zusatz zu behandeln. Wenn eine Entscheidung wichtig genug ist, um die Architektur oder den Betrieb zu beeinflussen, sollte ihr Grund nicht ausschließlich im Kopf der Person bleiben, die sie getroffen hat. Das gilt besonders dann, wenn ein System später von anderen übernommen oder weiterentwickelt wird.

Mehr zu diesem Vorgehen: Know → Change → Prove: Wie WordPress-Änderungen sicher werden.

Einfach für die Nutzung, klar für den Betrieb

Eine Sache hat sich bei mir verändert: Ich verstehe Einfachheit weniger als möglichst wenig Technik und mehr als eine Frage der richtigen Sichtbarkeit. Nutzerinnen und Nutzer sollen sich auf ihre Aufgabe konzentrieren können. Entwicklung und Betrieb brauchen dagegen genug Einblick, um das System nicht nur zu bedienen, sondern seine Folgen einzuschätzen.

Das verlangt Entscheidungen auf beiden Seiten. Was kann eine Oberfläche weglassen, ohne Orientierung zu verlieren? Welche technische Regel muss dokumentiert werden, damit eine spätere Änderung nicht auf Vermutungen beruht? Und welche Information hilft tatsächlich beim Betrieb, statt nur die Dokumentation länger zu machen?

Wenn ich diese Fragen nicht beantworten kann, ist das für mich ein Hinweis, dass die Komplexität noch nicht gut geordnet ist. Dann hilft es wenig, sie einfach in ein Handbuch zu verschieben. Ich muss erst herausfinden, welche Teile zusammengehören und welche Verantwortung an welcher Stelle liegt.

Meine Faustregel: Nutzer sollen möglichst wenig interne Komplexität sehen. Wer das System entwickelt oder betreibt, muss genug davon verstehen, um Änderungen begründen, prüfen und verantworten zu können.

Verwandte Beiträge

Nächster Schritt

Du planst eine Plattform und bist bei der Architektur noch offen?

Beschreibe dein Vorhaben. Wir klären, welche Entscheidungen zuerst anstehen.