Field Note: Wie ich technische Entscheidungen dokumentiere

Ich dokumentiere technische Entscheidungen nicht, um jede technische Abzweigung zu archivieren, sondern damit später noch erkennbar ist, warum ein System so gebaut wurde.

Das ist besonders wichtig, wenn ich ein gewachsenes System übernehme oder eine Architektur über längere Zeit weiterentwickle. Eine einzelne Entscheidung kann im Moment naheliegend wirken. Monate später ist oft nur noch das Ergebnis sichtbar: ein Plugin, ein Import, ein bestimmtes CMS oder eine selbst gehostete Komponente. Ohne den damaligen Zusammenhang sieht eine bewusste Abwägung schnell wie eine zufällige technische Eigenheit aus.

Ich brauche dafür kein akademisches Architekturpapier. Eine kurze, ADR-artige Notiz reicht. Sie hält fest, welches Problem ich lösen wollte, welche Optionen ich betrachtet habe, wofür ich mich entschieden habe und welche Nachteile ich damit akzeptiere.

Nicht jede Wahl braucht ein Dokument

Ich schreibe nicht jede kleine Implementierungsentscheidung auf. Wenn ich jede Variable, jede Einstellung und jeden internen Zwischenschritt festhalten würde, wäre die Dokumentation bald schwerer zu pflegen als das System selbst.

Mich interessieren Entscheidungen, die spätere Arbeit spürbar beeinflussen: die Wahl zwischen WordPress und Astro, zwischen einem eigenen Plugin und einem Fremdplugin, zwischen SaaS und Self-hosted oder zwischen einer API und einem Import. Auch eine Entscheidung für eine bestimmte Suchlösung kann dazugehören, wenn sie Teil der Architektur wird und nicht nur ein austauschbares Detail ist.

Ein nützlicher Test ist für mich: Würde jemand, der die Entscheidung nicht getroffen hat, später wahrscheinlich fragen, warum es so gelöst wurde? Wenn ja, lohnt sich eine Notiz. Nicht, weil jede Abweichung erklärt werden muss, sondern weil die Antwort für Wartung, Weiterentwicklung oder einen späteren Umbau relevant sein kann.

Dabei dokumentiere ich die Entscheidung, nicht die gesamte Diskussion. Die Notiz soll weder ein Protokoll noch eine vollständige Systembeschreibung ersetzen. Sie soll den entscheidenden Zusammenhang bewahren: Was war das Problem, welche Wege standen offen und welche Folgen hat der gewählte Weg?

Vier Punkte, die ich festhalte

Meine Notiz besteht aus vier Teilen. Ich halte sie bewusst knapp und benenne die Dinge direkt.

Problem: Was musste gelöst werden? Ich beschreibe hier nicht schon die Lösung, sondern die Ausgangslage oder Einschränkung. Je genauer das Problem gefasst ist, desto leichter lässt sich später beurteilen, ob die Entscheidung noch passt.

Optionen: Welche realistischen Möglichkeiten habe ich betrachtet? Es müssen nicht alle theoretisch denkbaren Varianten sein. Wichtig sind die Optionen, zwischen denen tatsächlich abgewogen wurde. Dazu kann auch gehören, eine bestehende Lösung beizubehalten oder zunächst nichts zu verändern.

Entscheidung: Was wird umgesetzt? Hier formuliere ich die Wahl klar, ohne sie mit einer langen Rechtfertigung zu verwischen. Wenn die Entscheidung an Bedingungen geknüpft ist, gehören auch diese dazu.

Konsequenzen: Was wird durch die Wahl einfacher, schwieriger oder unmöglich? Vor allem halte ich fest, welche Nachteile ich bewusst in Kauf nehme. Dieser Teil ist für mich kein Kleingedrucktes, sondern der Kern der Notiz.

Die vier Punkte verhindern, dass ich nur ein Ergebnis festhalte. „Wir nutzen Astro“ sagt wenig, wenn später unklar ist, welche Anforderungen zu dieser Wahl geführt haben und welche Arbeit damit verbunden ist. Genauso unvollständig wäre eine Liste von Vor- und Nachteilen ohne eine eindeutige Entscheidung.

Eine gute technische Entscheidung ist für mich nicht die Lösung ohne Nachteile. Es ist die Lösung, deren Nachteile ich bewusst akzeptiere.

Entscheidungen an echten Systemen festhalten

Bei Garten 1x1 ist die Migration von WordPress zu Astro ein Beispiel für eine Entscheidung, die mehr umfasst als die Wahl eines Frontends. Der Wechsel wurde mit einem einmaligen TypeScript-Skript umgesetzt, das den WXR-Export in Markdown überführt. Die Inhalte liegen anschließend in Content Collections mit einem Zod-Schema; die Suche läuft über Pagefind.

In einer Entscheidungsnotiz würde ich deshalb nicht nur „WordPress oder Astro?“ festhalten. Ich würde das Problem benennen, die betrachteten Wege dokumentieren und dann die konkrete Entscheidung beschreiben: Migration zu Astro, Überführung der Inhalte und Modellierung in Collections. Als Konsequenzen gehören auch die Teile dazu, die diese Architektur voraussetzt oder mit sich bringt. So bleibt sichtbar, dass nicht ein einzelnes Werkzeug gewählt wurde, sondern ein zusammenhängender Weg für Inhalte, Datenstruktur und Suche.

Bei erlebe-nrw treffen Datenquellen und Produktentscheidungen aufeinander. Die Plattform verarbeitet rund 8.300 Ausflugsziele aus OpenStreetMap, Wikidata, Wikivoyage und dem Data Hub Tourismus NRW. Die Daten laufen durch eine nummerierte Python-Pipeline von SQLite über JSONL nach Astro. Quelle und Stand werden bei jeder Angabe mitgeführt.

Hier würde ich die Entscheidung, OpenStreetMap-Daten einzubeziehen, nicht als isolierte Zustimmung zu „Open Data“ dokumentieren. Relevant ist auch, wie die Herkunft und der Stand der Angaben im fertigen System erkennbar bleiben. Die Notiz sollte die gewählte Datenbasis und die damit verbundene Verantwortung für Quellenangaben festhalten. Welche Konsequenz ich akzeptiere, hängt dabei nicht nur von der Quelle ab, sondern auch davon, wie die Daten verarbeitet und veröffentlicht werden.

Ein anderes Beispiel ist die Frage API oder Import. Beim Projekt eisenross importiert ein eigenes PHP/MySQL-Backend Awin-Feeds. Produkte werden erst nach Freigabe öffentlich. Eine Notiz zu dieser Art von Entscheidung sollte nicht bei „Import gewählt“ enden. Sie sollte festhalten, was der Import im eigenen System ermöglicht und welche Verantwortung dadurch dort liegt: etwa für die Verarbeitung der Daten und den Weg bis zur Freigabe. Welche Vorteile oder Nachteile im konkreten Vergleich ausschlaggebend waren, schreibe ich nur auf, wenn sie tatsächlich Teil der Entscheidung waren.

Nachteile gehören in die Notiz

Ich merke bei technischen Entscheidungen oft, wie verführerisch es ist, die gewählte Lösung im Nachhinein als eindeutig überlegen darzustellen. Das hilft niemandem. Eine Notiz, die nur Vorteile nennt, ist eher eine Verkaufsbegründung als eine Arbeitsgrundlage.

Wenn ich ein eigenes Plugin statt eines Fremdplugins in Betracht ziehe, notiere ich nicht nur, was ich daran passend finde. Ich halte auch fest, dass eine eigene Lösung Pflege und Verantwortung mit sich bringt. Wenn SaaS und Self-hosted gegeneinanderstehen, gehört in die Notiz, welche Abhängigkeiten oder Betriebsaufgaben ich mit der jeweiligen Wahl verbinde. Das Ergebnis muss nicht immer Eigenentwicklung oder Self-hosted sein. Ich baue lieber kleine spezialisierte Werkzeuge, wenn es passt, aber nicht alles selbst.

Der entscheidende Punkt ist, diese Überlegungen nicht nachträglich als Tatsachen auszugeben. Ich halte fest, was ich tatsächlich abgewogen habe. Wenn eine Frage offen war oder eine Annahme die Entscheidung beeinflusst hat, benenne ich das. Eine knappe, ehrliche Notiz ist hilfreicher als eine ausgefeilte Begründung, die den tatsächlichen Entscheidungsweg glättet.

Was ich heute anders mache: Ich frage nicht zuerst, welche Lösung die meisten Vorteile verspricht. Ich frage, welches Problem gelöst werden muss und welche Nachteile ich im Betrieb tragen kann. Erst danach formuliere ich die Entscheidung.

Eine Notiz, die später noch hilft

Technische Entscheidungen zu dokumentieren heißt für mich nicht, die Zukunft vorherzusagen. Anforderungen, Inhalte und Rahmenbedingungen können sich ändern. Eine gute Notiz macht eine spätere Neubewertung eher möglich: Sie zeigt, worauf die damalige Entscheidung beruhte und welche Folgen bewusst akzeptiert wurden.

Wenn sich das Problem verändert hat, kann auch die Entscheidung überprüft werden. Wenn die Nachteile inzwischen zu schwer wiegen, lässt sich gezielter über eine Alternative sprechen. Und wenn die ursprünglichen Bedingungen noch gelten, muss niemand dieselbe Abwägung von vorn beginnen.

Ich halte solche Notizen deshalb nah an der Arbeit, nicht in einem separaten Dokumentationsprojekt, das irgendwann veraltet. Sie müssen nicht lang sein. Vier klare Punkte reichen oft, solange sie ehrlich beantworten, was das Problem war, welche Optionen es gab, was entschieden wurde und was diese Wahl kostet.

Meine Faustregel: Ich dokumentiere eine technische Entscheidung dann, wenn sie die spätere Arbeit beeinflussen kann. Und ich nenne nicht nur, was ich gewählt habe, sondern auch den Nachteil, den ich damit bewusst in Kauf nehme.

Weiterführend

• Was eine gute Übergabe enthält
• WordPress technisch dokumentieren
• Astro oder WordPress