Jeder kennt die Situation: Ein kritischer Dienst fällt aus. Das Telefon läuft heiß. Der Slack-Kanal brennt. Und irgendjemand — meist der neue Kollege, der drei Wochen im Haus ist — fragt: „Gibt’s dazu eine Doku?“
Stille.
Dann, nach einer halben Stunde Suchen, findet jemand ein Confluence-Dokument, das zuletzt 2021 aktualisiert wurde. Die Servernamen stimmen nicht mehr. Die Ports sind falsch. Der beschriebene Workaround funktioniert längst nicht mehr, weil zwischenzeitlich ein Major-Upgrade stattfand, das niemand dokumentiert hat.
Und jetzt — jetzt, mitten im Ausfall, unter Zeitdruck, mit Management, das alle fünf Minuten nach dem Status fragt — jetzt soll Dokumentation entstehen. Gute Dokumentation. Vollständig. Nachvollziehbar.
Das ist das Doku-Paradox: Dokumentation ist genau dann am wichtigsten, wenn sie am schwersten zu erstellen ist.
Die drei Zustände von Dokumentation
Dokumentation existiert in genau drei Zuständen. Und jeder ist schlimmer als der vorherige.
Zustand 1: Gar nicht
Kein Wiki-Eintrag. Kein README. Nichts im Git-Repo. Die Konfiguration existiert nur auf dem Server und im Kopf der Person, die sie aufgesetzt hat.
Das ist offensichtlich schlecht. Aber — und das wird oft übersehen — es hat einen Vorteil: Es ist ehrlich. Jeder, der ankommt, weiß sofort: Hier gibt es keine Doku. Ich muss fragen. Ich muss vorsichtig sein. Ich muss mich auf nichts verlassen, was ich finde.
Das ist unangenehm, aber klar.
Zustand 2: Veraltet
Jemand hat 2021 eine schöne Doku geschrieben. Architekturdiagramme. Schritt-für-Schritt-Anleitungen. Tabellen mit Servernamen und IPs. Richtig gute Arbeit.
Aber jetzt ist es 2026. Fünf Server aus der Doku existieren nicht mehr. Drei neue sind dazugekommen. Der Load Balancer wurde durch einen anderen ersetzt. Die SSL-Zertifikate rotieren mittlerweile automatisch, aber die Doku beschreibt noch den manuellen Prozess.
Veraltete Doku ist gefährlicher als keine Doku. Warum? Weil sie Vertrauen erweckt, das nicht gerechtfertigt ist. Du liest das Dokument, denkst „Alles klar, ich verstehe das System“ — und handelst auf Basis von Informationen, die schlicht falsch sind.
Beim Zustand „gar nicht“ fragst du nach. Beim Zustand „veraltet“ glaubst du, du müsstest nicht fragen.
Zustand 3: Falsch
Das ist die Eskalation von Zustand 2. Veraltete Doku könnte noch stimmen. Falsche Doku stimmt aktiv nicht — und sieht dabei aus, als würde sie stimmen.
Falsche Doku ist das Ergebnis von „ich hab das schnell angepasst, das stimmt so“ — wenn es nicht stimmt. Von copy-paste aus einer anderen Doku, bei der ein Detail übersehen wurde. Von jemandem, der schreibt, wie etwas funktionieren sollte, nicht wie es funktioniert.
Falsche Doku ist aktiv schädlich. Sie führt zu Fehlern, die ohne die Doku nicht passiert wären. Sie ist eine Zeitbombe.
Die bittere Erkenntnis: Der Weg von „keine Doku“ zu „falsche Doku“ ist kürzer als man denkt. Ein halbgutes Update eines alten Dokuments reicht.
Warum niemand dokumentiert
Die Gründe sind banal und universell.
Kein unmittelbarer Nutzen. Wenn du eine Konfiguration änderst, hast du einen sofortigen Effekt: Der Dienst funktioniert wieder. Die Pipeline läuft. Der Bug ist weg. Wenn du dieselbe Änderung dokumentierst, passiert — nichts. Zumindest nichts, das du spürst. Der Nutzen ist latent, diffus, irgendwann in der Zukunft.
Kein Deadline-Druck. Features haben Deadlines. Bugs haben SLAs. Security-Patches haben CVE-Nummern und verantwortliche Offenlegungszeitpläne. Dokumentation hat nichts davon. Niemand ruft am Freitag um 17 Uhr an und sagt „Die Doku für den neuen Mailserver muss bis Montag fertig sein.“
„Das weiß ich doch im Kopf.“ Das ist der gefährlichste Grund, weil er wahr ist — im Moment. Du hast das System aufgesetzt. Du kennst jeden Knopf, jeden Workaround, jeden historischen Grund, warum das so ist und nicht anders. Warum solltest du aufschreiben, was du ohnehin weißt? Das wäre redundant. Ineffizient.
Bis du kündigst. Krank wirst. Urlaub machst. Oder — und das passiert öfter als man denkt — bis du es vergisst. Drei Monate später, unter Stress, um 2 Uhr nachts, erinnerst du dich nicht mehr, warum der DNS-Resolver auf genau diesem Host auf Port 5353 lauscht. Oder ob das noch gebraucht wird. Oder ob das ein temporärer Hack war, der längst weg sollte.
Und dann machst du genau das, was man nicht machen sollte: Du lässt es stehen, weil du dir nicht sicher bist, ob etwas davon abhängt.
Die Kosten der fehlenden Doku
Die Kosten sind massiv, aber sie fallen selten dem zu, der die Doku nicht geschrieben hat. Sie externalisieren sich — auf Kollegen, auf Nachfolger, auf das Projekt.
Onboarding-Zeiten
Ein neuer Kollege braucht bei guter Dokumentation vielleicht zwei Wochen, um produktiv zu werden. Bei fehlender Doku sind es zwei Monate. In denen fragt er alles. In denen erfahrene Kollegen unterbrochen werden. In denen er Fehler macht, die ein Readme in fünf Minuten verhindert hätte.
Onboarding-Kosten sind die sichtbarste und messbarste Konsequenz. Und trotzdem wird in den seltensten Fällen der Dokumentationsmangel als Grund identifiziert. Es heißt dann „Der Einarbeitungsprozess muss optimiert werden“ — statt „Wir haben keine Doku“.
Single Points of Failure
Wenn eine Person die einzige ist, die ein System versteht, ist das ein Single Point of Failure. Nicht das System — die Person. Und Menschen sind deutlich anfälliger als gut administrierte FreeBSD-Server. Sie kündigen. Sie werden krank. Sie gewinnen im Lotto und ziehen nach Neuseeland.
Jedes System, das nur eine Person versteht, ist ein Risiko. Und dieses Risiko wird in den seltensten Fällen in der Risikoanalyse auftauchen, weil — ihr ahnt es — niemand dokumentiert hat, dass das System nur von einer Person verstanden wird.
Update-Angst
„Wir können nicht updaten, wir wissen nicht, ob das noch funktioniert.“ Das ist der Satz, der jeden Admin das Fürchten lehrt. Weil irgendjemand vor drei Jahren einen Patch auf einem System eingespielt hat, der einen Edge Case abdeckt, der nirgends dokumentiert ist. Und jetzt soll ein Major-Upgrade gemacht werden, und niemand weiß, ob dieser Patch noch relevant ist, ob er noch gebraucht wird, oder ob er längst in den Upstream geflossen ist.
Also bleibt das System auf einer alten Version. Aus Angst. Und aus mangelndem Vertrauen in die eigene Dokumentation, die nicht existiert.
Dienstleister-Konflikte
„Mein Teil funktioniert.“ — Der Klassiker bei verteilten Systemen mit externen Dienstleistern. Die Datenbank-Admins sagen „Die DB läuft“. Die App-Entwickler sagen „Die App läuft“. Die Netzwerk-Admins sagen „Das Netzwerk läuft“. Und trotzdem funktioniert das Gesamtsystem nicht.
Jeder kennt nur seinen Teil. Niemand kennt die Schnittstellen. Niemand hat dokumentiert, wie die Teile zusammenhängen. Und jetzt sitzen alle im Kriegsrat und zeigen mit dem Finger aufeinander.
Gute Dokumentation der Schnittstellen — der Verträge zwischen den Systemen, nicht der Systeme selbst — hätte das verhindert. Aber Schnittstellen zu dokumentieren ist noch unwirtschafter als Systeme zu dokumentieren, weil es keinen klaren Eigentümer gibt.
Praktische Lösungen
Genug der Diagnose. Hier ist die Therapie.
Living Documentation: Doku als Code
Der beste Zustand von Dokumentation ist der, in dem sie nicht gepflegt werden muss, weil sie sich selbst pflegt. Living Documentation bedeutet: Die Dokumentation ist nicht ein separates Dokument, das man aktualisieren muss. Sie ist Teil des Codes, der ohnehin gepflegt wird.
Ansible-Playbooks als Dokumentation. Ein gut geschriebenes Ansible-Playbook ist die Dokumentation. Jede Task beschreibt, was auf dem System passiert. Die Variablen zeigen, welche Parameter verwendet werden. Die Handler zeigen, was bei Änderungen passiert. Wenn das Playbook aktuell ist, ist die Doku aktuell. Wenn nicht — dann läuft das Playbook auch nicht, und das Problem ist ein anderes.
Ein Beispiel:
# roles/mailserver/tasks/main.yml
# Postfix + Dovecot Mailserver Setup
# See: https://wiki.tgeppert.de/mailserver for architecture overview
- name: Install Postfix and Dovecot
ansible.builtin.package:
name:
- postfix
- dovecot
- dovecot-pigeonhole
state: present
tags: [install, mail]
- name: Configure Postfix virtual domains
ansible.builtin.template:
src: postfix/virtual_domains.j2
dest: /etc/postfix/virtual_domains
owner: root
group: wheel
mode: '0644'
notify: Reload Postfix
tags: [config, mail]
Das Playbook sagt dir: Welche Pakete sind installiert? Welche Konfigurationsdateien gibt es? Welche Berechtigungen? Welche Tags für selektives Ausführen? Du musst kein separates Dokument pflegen — das Playbook ist das Dokument.
Terraform-Module als Architektur-Beschreibung. Dasselbe gilt für Terraform. Ein Terraform-Modul beschreibt die Infrastruktur deklarativ. Die Ressourcen, die Abhängigkeiten, die Variablen — das alles ist gleichzeitig Code und Dokumentation.
# modules/webapp/main.tf
# Web Application Stack: LB -> App -> DB
# Last reviewed: 2026-04
resource "proxmox_vm_qemu" "webapp" {
name = "webapp-${var.environment}"
target_node = var.proxmox_node
clone = "freebsd-14-template"
# ...
}
Wenn jemand die Architektur verstehen will, liest er das Terraform-Modul. Wenn etwas geändert wird, ändert sich das Modul. Die Doku aktualisiert sich von selbst — weil sie identisch mit dem Code ist.
ZFS-Snapshots als Änderungsprotokoll
Hier wird es interessant für die FreeBSD-Fraktion unter uns. ZFS hat eine Eigenschaft, die fast niemand für Dokumentation nutzt, die aber extrem wertvoll ist: Snapshots.
Jeder ZFS-Snapshot ist ein punktuelles Abbild des Dateisystems. Wenn du Snapshots regelmäßig erstellst — was du ohnehin tun solltest —, hast du eine chronologische Aufzeichnung jeder Änderung auf Dateisystemebene.
# Snapshot erstellen (z.B. vor einem Upgrade)
zfs snapshot zroot/usr/local@pre-upgrade-2026-04-23
# Was hat sich seit dem letzten Snapshot geändert?
zfs diff zroot/usr/local@daily-2026-04-22 zroot/usr/local@daily-2026-04-23
Die Ausgabe von zfs diff zeigt dir exakt, welche Dateien hinzugekommen, geändert oder gelöscht wurden. Das ist kein Ersatz für eine menschliche Dokumentation — aber es ist ein Änderungsprotokoll, das sich nicht vergessen werden kann. Es passiert automatisch.
Kombiniert mit einem Commit-Message-Stil für Snapshot-Namen (@pre-upgrade-2026-04-23, @post-dovecot-config), entsteht eine Art Git-Log auf Dateisystemebene. Ohne dass jemand ein Git-Log pflegen muss.
Die Documentation-First-Regel: Kein System ohne README im Repo
Hier ist eine einfache Regel, die den Charakter einer Organisationskultur verändert: Kein System geht live ohne ein README im zugehörigen Repository.
Nicht ein perfektes README. Nicht eine 20-seitige Architekturdokumentation. Ein README. Eine Seite. Was ist das? Wie starte ich es? Wo läuft es? Wen frag ich, wenn etwas kaputt ist?
# Mailserver (Postfix + Dovecot)
## Was ist das?
Zentrale Mail-Infrastruktur für @tgeppert.de und @beispiel.de
## Wo läuft es?
- Host: mx01.tgeppert.de (Proxmox VM, FreeBSD 14)
- IP: 192.168.1.50 (intern), 203.0.113.50 (extern)
- Ansible-Playbook: `ansible/mailserver.yml`
## Wie starte ich es?
bash
ansible-playbook ansible/mailserver.yml –tags install,config
## Wen frag ich?
Thorsten Geppert (thorsten@tgeppert.de)
## Bekannte Probleme
- DKIM-Signaturen müssen nach Cert-Rotation manuell geprüft werden
- Siehe Issue #42
Das ist keine Rocket Science. Das ist fünf Minuten Arbeit. Und es ist mehr Dokumentation, als 90% der Systeme in 90% der Unternehmen haben.
Die Regel ist einfach: Kein Deployment ohne README. Keine Ausnahmen. Wenn das README fehlt, geht der Pull Request nicht durch. Punkt.
Warum FreeBSDs Manpage-Kultur ein Vorbild ist
FreeBSD macht etwas richtig, das viele Linux-Distributionen vernachlässigen: Die Manpages sind erstklassig.
Wenn du auf einem FreeBSD-System man rc.conf eingibst, bekommst du eine detaillierte, aktuelle, durchsuchbare Dokumentation aller verfügbaren Systemparameter. Mit Beispielen. Mit Defaults. Mit Querverweisen. Und — das ist der entscheidende Punkt — die Manpages werden zusammen mit dem Code gepflegt. Sie sind Teil des gleichen Repositories, desselben Release-Prozesses, derselben Review-Kultur.
Das funktioniert, weil in der FreeBSD-Community die Erwartung besteht: Wenn du ein Feature einreichst, kommt die Doku mit. Ein Patch ohne Manpage-Update wird nicht gemerged. Nicht als Strafe, sondern weil Dokumentation als Teil des Features verstanden wird — nicht als Nachgang.
Diese Kultur lässt sich nicht über Nacht einführen. Aber das Prinzip lässt sich übertragen: Doku und Code gehören in denselben Review-Prozess. Wenn der Pull Request das Feature bringt, muss er auch die Doku bringen. Sonst kein Merge.
Git-Repositories für Konfigurationen
Die Idee ist simpel, aber die Umsetzung hat weitreichende Konsequenzen: Jede Konfiguration, die auf einem Server lebt, gehört in ein Git-Repository.
Nicht nur der Anwendungscode. Die nginx-Konfiguration. Die pf-Regeln. Die cron-Jobs. Die /etc/rc.conf. Alles.
Warum?
- Versionierung. Du kannst sehen, was sich wann geändert hat. Und — wichtiger noch — du kannst zurückrollen.
git log /etc/nginx/sites-available/example.conf zeigt dir die Geschichte. git diff HEAD~1 zeigt dir die letzte Änderung. Das ist Dokumentation, die sich selbst schreibt. - Verteilung. Mit Ansible, Puppet oder einfach
git pull verteilst du Konfigurationen konsistent. Kein „auf Server A ist die alte Version, auf Server B die neue“. - Review. Änderungen an der Konfiguration können wie Code-Änderungen behandelt werden: Pull Request, Review, Merge. Plötzlich hat jede Änderung einen Kontext — wer, wann, warum.
- Automatische Dokumentation. Die Commit-Historie ist das Änderungsprotokoll. Kein Mensch muss ein Change-Log pflegen. Git macht es.
# /etc in ein Git-Repo verwandeln (FreeBSD)
cd /etc
git init
git add rc.conf pf.conf nginx/ postfix/
git commit -m "Initial commit: current server configuration"
# Änderung tracken
git add rc.conf
git commit -m "Enable moused on /dev/ums0 for USB mouse support"
Das ist kein Ersatz für eine Architekturdokumentation. Aber es ist ein Fundament, auf dem man aufbauen kann. Und es kostet fast nichts.
Automatische Doku durch Monitoring und Logging
Die letzte Säule: Monitoring und Logging als automatische Dokumentation.
Monitoring-Systeme wie Prometheus, Grafana, Icinga oder Zabbix erfassen permanent den Zustand deiner Systeme. Das ist nicht nur operativ wertvoll — es ist auch Dokumentation.
- Grafana-Dashboards zeigen die aktuelle Architektur. Welche Dienste laufen? Welche Metriken werden erfasst? Welche Schwellwerte gelten? Ein gut gebautes Dashboard ist eine visuelle Dokumentation des Systems.
- Alert-Regeln dokumentieren, was als problematisch gilt. Wenn der Alert „Mailqueue > 500″ existiert, ist das eine Aussage: Eine Mailqueue über 500 Nachrichten ist nicht normal. Das ist Dokumentation.
- Log-Aggregation (mit Loki, Elastic oder einfach
syslog) zeigt, was passiert ist. Die Logs sind das Tagebuch des Systems — automatisch, unausweichlich, nicht vergesslich.
Die Idee: Nicht alles muss von Hand geschrieben werden. Monitoring und Logging produzieren kontinuierlich Dokumentation. Die Kunst besteht darin, diese Daten so aufzubereiten, dass sie auch als Dokumentation verständlich sind — und nicht nur als Rohdaten.
Das 5-Minuten-Prinzip
Alle Strategien oben helfen, aber sie lösen nicht das grundlegende Problem: den Moment, in dem du etwas reparierst und denkst „Das muss ich nicht aufschreiben, das ist nur ein Quick-Fix.“
Hier kommt das 5-Minuten-Prinzip: Wenn du etwas reparierst, nimm dir fünf Minuten Zeit und schreib auf, was das Problem war.
Nicht „ausführlich dokumentieren“. Nicht „ein Confluence-Dokument erstellen“. Fünf Minuten. In dein Notizbuch, in ein README.md im Repo, in den Commit-Message-Body, in den Slack-Kanal — irgendwohin.
## 2026-04-23: Mailqueue stauete sich
**Problem:** Mailqueue auf mx01 lief über, weil Dovecot-AUTH-Timeout auf 10s stand.
**Lösung:** Timeout auf 30s erhöht. Siehe commit abc123.
**Ursache:** Nach dem Update auf Dovecot 2.4 ist der Default-Timeout gesunken.
**Follow-up:** Prüfen, ob 30s ausreichen oder ob wir die Connection-Pooling-Logik anpassen müssen.
Das ist keine perfekte Dokumentation. Aber es ist eine Dokumentation. Und sie ist unendlich viel besser als die Alternative: drei Monate später dasselbe Problem, dieselbe Sucherei, derselbe Aufwand.
Das 5-Minuten-Prinzip funktioniert, weil es den inneren Schweinehund umgeht. „Fünf Minuten“ ist kein „ich muss erst ein Dokument erstellen“. Es ist eine kurze, machbare Investition. Die Hürde ist niedrig genug, dass sie im Alltag überwindbar ist. Und der Effekt kumuliert: Nach einem Jahr hast du eine Sammlung von Problembeschreibungen und Lösungen, die wertvoller ist als jedes Architektur-Wiki.
Das eigentliche Problem
Das Doku-Paradox ist kein Technologie-Problem. Es ist ein Kultur-Problem.
Dokumentation wird als Nachgang behandelt. Als „das, was man macht, wenn die eigentliche Arbeit fertig ist“. Als das, was bei Zeitdruck zuerst gestrichen wird. Als das, was keine Deadline hat und deshalb nie fertig wird.
Aber Dokumentation ist kein Nachgang. Dokumentation ist Teil des Systems.
Ein System ohne Dokumentation ist wie ein Programm ohne Tests. Es mag jetzt funktionieren. Aber du kannst nicht verifizieren, dass es funktioniert. Du kannst es nicht sicher ändern. Du kannst es nicht weitergeben. Es ist fragil.
Die drei Zustände von Dokumentation — gar nicht, veraltet, falsch — sind keine Stadien eines Prozesses. Sie sind Symptome einer Kultur, die Dokumentation als optional betrachtet.
Die Lösungen — Living Documentation, Git-Repositories für Konfigurationen, ZFS-Snapshots, Manpage-Kultur, das 5-Minuten-Prinzip — haben eines gemeinsam: Sie machen Dokumentation nicht optional. Sie bauen sie in den Prozess ein. Sie machen es einfacher, Dokumentation zu erstellen, als sie wegzulassen.
Und das ist der Hebel. Nicht Appell. Nicht „wir sollten mehr dokumentieren“. Sondern Systeme und Prozesse, in denen Dokumentation der Weg des geringsten Widerstands ist.
TL;DR
- Das Paradox: Doku ist am wichtigsten, wenn sie am schwersten zu erstellen ist. Unter Zeitdruck. Nach einem Ausfall. Wenn der Admin kündigt.
- Drei Zustände: Gar nicht (ehrlich), veraltet (gefährlich), falsch (aktiv schädlich). Jeder ist schlimmer als der vorherige.
- Warum nicht: Kein unmittelbarer Nutzen, kein Deadline-Druck, „Das weiß ich im Kopf.“
- Die Kosten: Langes Onboarding, Single Points of Failure, Update-Angst, Dienstleister-Konflikte.
- Lösungen: Doku als Code (Ansible, Terraform), ZFS-Snapshots als Change-Log, README-Pflicht, Manpage-Kultur, Git für Configs, Monitoring als automatische Doku.
- 5-Minuten-Prinzip: Fünf Minuten aufschreiben, was das Problem war. Immer.
- Dokumentation ist kein Nachgang. Sie ist Teil des Systems.