Wissensdokumentation in DevOps-Teams: Bus-Faktor senken

Der Bus-Faktor ist unangenehm zu messen, weil das Ergebnis selten schmeichelt. Wenn eine Person das Unternehmen verlässt oder schlicht im Urlaub ist und ein kritisches System damit unwartbar wird, ist das kein Pech. Das ist ein strukturelles Problem. Dieser Artikel zeigt, warum Wissensdokumentation in DevOps-Teams so oft scheitert und welche Ansätze tatsächlich etwas ändern.

Was der Bus-Faktor wirklich misst

Der Begriff klingt makaber, ist aber präzise: Wie viele Personen müssten gleichzeitig ausfallen, damit ihr Team ein kritisches System nicht mehr betreiben kann? Eine Zahl größer als zwei gilt als solide. In vielen KMU ist die Antwort eins – eines der häufigsten DevOps-Probleme in KMU.

Das ist kein Vorwurf an die betreffenden Personen, es ist ein Symptom davon, wie Infrastruktur in kleinen Teams typischerweise entsteht – und warum fehlende DevOps-Rollen zum Risiko werden. Jemand baut das System auf, lernt dabei, macht Entscheidungen. Diese Entscheidungen landen selten in einem Dokument. Sie landen im Kopf.

Warum das gefährlich ist: Ein Kubernetes-Cluster hat viele bewegliche Teile. Welcher Namespace gehört zu welchem Service? Warum läuft der Ingress-Controller auf dieser spezifischen Konfiguration? Warum wurde damals Helm statt Kustomize gewählt? Wenn niemand die Antworten kennt außer einer Person, habt ihr ein Wissensmonopol und Wissensmonopole sind teure Risiken.

Warum Dokumentation in kleinen Teams immer scheitert

Dokumentation scheitert in kleinen Teams selten an fehlendem Willen, sondern an fehlender Passung zur Realität: wenig Zeit, hohe Taktung, ständig wechselnde Prioritäten. Und genau deshalb treten zwei Muster fast immer auf.

Problem 1: Dokumentation wird als Nacharbeit behandelt (und verliert damit immer)

In kleinen Teams ist der Tag voll mit „echter" Arbeit: Feature fertig bekommen, Kundenproblem lösen, Release stabil halten. Dokumentation landet automatisch am Ende der Kette – als Post-it am Ticket oder als „machen wir später".

Das klingt harmlos, hat aber mehrere systematische Effekte:

• Die Motivation ist weg, wenn das Problem gelöst ist: Sobald ein Incident behoben oder ein Feature shipped ist, fühlt sich Dokumentation wie Bürokratie an. Der „Pain" ist vorbei, also fehlt der Druck, es sauber zu notieren.
• Kontext verschwindet extrem schnell: Warum wurde eine Entscheidung getroffen? Welche Alternative wurde verworfen? Welche Annahme war damals wichtig? Nach ein paar Tagen ist das Wissen schon nur noch „ungefähr" da und nach ein paar Wochen wird es rekonstruiert statt dokumentiert.
• Der nächste Task drängt sich dazwischen: Kleine Teams arbeiten selten mit großzügigen Zeitpuffern. Wenn das nächste Ticket schon wartet, wirkt Dokumentation wie Luxus. Und Luxus gewinnt nie gegen ein akutes To-do.
• Die Qualität wird schlechter, je später man schreibt: Wer nachträglich dokumentiert, schreibt häufig vage („wir haben X so gemacht") statt konkret („wir haben X aus Grund Y, mit Risiko Z, und Rollback ist A"). Diese vage Dokumentation hilft im Ernstfall kaum.

Das Ergebnis ist predictable: Dokumentation entsteht entweder gar nicht oder sie entsteht als „Snapshot" von gestern. Aber Infrastruktur ist kein Snapshot, sie verändert sich. Und wenn Dokumentation nicht Teil des normalen Workflows ist (z.B. Review-Checklisten, PR-Templates, Definition of Done, Runbook-Update bei Alerts), wird sie zur Altlast.

Problem 2: Das Wiki wird groß und damit unglaubwürdig (Information-Entropy)

Der zweite Klassiker ist das „Wiki-Paradox": Man versucht, das Dokumentationsproblem zu lösen, indem man mehr Dokumentation schreibt. Das erzeugt Masse, aber nicht automatisch Nutzen.

Mit der Zeit passiert Folgendes:

• Wikis wachsen schneller, als sie gepflegt werden können: Jede neue Komponente erzeugt neue Seiten, jede Änderung erzeugt neue Abweichungen. Pflege ist Daueraufgabe, aber im Alltag wird sie als einmaliger Task behandelt.
• Niemand weiß, was noch stimmt: Sobald ein Team 1–2 Mal erlebt hat, dass eine Wiki-Seite veraltet oder falsch ist, sinkt das Vertrauen. Und ohne Vertrauen wird das Wiki nicht mehr konsultiert.
• Suche ersetzt Struktur und scheitert: Statt klarer „Golden Path"-Dokumente gibt es viele Einzelseiten. Menschen suchen dann nach Stichworten, bekommen fünf Treffer und müssen raten, welcher gültig ist.
• Dokumentation wird zu „Archäologie": Neue Teammitglieder lesen sich durch historische Einträge, ohne zu wissen, was heute relevant ist. Das kostet Zeit, schafft Unsicherheit und führt am Ende doch wieder zur gleichen Lösung: jemanden fragen.

Auch hier ist der Effekt paradox: Es gibt „viel" Dokumentation, aber sie reduziert die Abhängigkeit von Einzelpersonen kaum, weil das Team sie nicht als zuverlässige Quelle nutzt.

Warum diese zwei Probleme sich gegenseitig verstärken

Beide Muster hängen zusammen:

• Weil Dokumentation als Nacharbeit passiert, wird sie unregelmäßig und fragmentiert.
• Weil sie fragmentiert ist, wächst das Wiki chaotisch.
• Weil das Wiki chaotisch ist, sinkt das Vertrauen.
• Weil das Vertrauen sinkt, dokumentiert man noch weniger („liest eh keiner").

Und sobald das passiert, wird Wissen wieder mündlich verteilt: per Slack-Nachricht, im Call, auf Zuruf. Das ist kurzfristig effizient – aber es baut den Bus-Faktor wieder auf.

Was das praktisch bedeutet

Wenn du dieses Kapitel liest und denkst „ja, genau so ist es bei uns", ist das kein individuelles Versagen. Es ist ein Signal, dass euer Dokumentationsansatz nicht zur Teamgröße und zum Arbeitsmodus passt.

Die Lösung ist deshalb fast nie: „schreibt mehr". Die Lösung ist: schreibt weniger, aber integrierter und verlässlicher und verlagert so viel wie möglich in selbstdokumentierende Artefakte (IaC in Git, nachvollziehbare Deployments, klare Defaults, kurze Runbooks), damit Dokumentation nicht gegen die Realität arbeiten muss, sondern mit ihr.

Infrastructure as Code als lebendige Dokumentation

Der wirksamste Schritt gegen Wissensilos ist nicht mehr Dokumentation zu schreiben. Es ist, Systeme so zu bauen, dass sie sich selbst dokumentieren.

Infrastructure as Code ist genau das. Wenn euer Cluster-Setup in Git liegt, ist der aktuelle Zustand des Systems jederzeit nachvollziehbar. Wer wissen will, wie ein Deployment konfiguriert ist, schaut ins Repository – nicht in den Kopf eines Kollegen.

Das setzt voraus, dass IaC tatsächlich die Single Source of Truth ist. Wenn Konfigurationen manuell überschrieben werden und das Repository nicht mehr den echten Zustand abbildet, verliert ihr den Vorteil sofort. Disziplin im Prozess ist hier wichtiger als das Tooling.

Terraform, Helm und Kustomize im Vergleich

Für Kubernetes-Umgebungen haben sich drei Ansätze etabliert:

• Helm bietet Templates mit Variablen. Der Code ist gut lesbar, solange die Values-Dateien gepflegt sind. Für wiederkehrende Deployments ein solider Standard.
• Kustomize arbeitet mit Overlays auf Basis-Manifesten. Weniger Abstraktion, dafür näher am nativen Kubernetes-YAML. Gut für Teams, die lieber direkt mit Manifesten arbeiten.
• Terraform mit dem Kubernetes-Provider eignet sich gut, wenn Infrastruktur und Applikationen aus einer Hand verwaltet werden sollen. Der Einstieg ist steiler, die Konsistenz über mehrere Umgebungen hinweg aber schwer zu schlagen.

Welches Tool besser zu eurem Team passt, hängt weniger von den Features ab als davon, wie ihr arbeitet. Entscheidend ist: Was auch immer ihr wählt, es muss in Git liegen und der tatsächliche Zustand muss sich darin widerspiegeln.

# Beispiel: Helm-Deployment mit expliziten Values für Nachvollziehbarkeit
helm upgrade --install my-service ./chart \
  --values ./environments/production/values.yaml \
  --namespace production \
  --atomic

Warum IaC für KMU nicht immer die beste Antwort ist

Infrastructure as Code ist ein starkes Prinzip, aber es hat eine oft unterschätzte Voraussetzung: Es muss auch jemanden geben, der die Infrastruktur als Code dauerhaft „besitzt".

Gerade in KMU tritt häufig eines (oder mehrere) dieser Probleme auf:

• Hohe Einstiegshürde und Tool-Overhead: Terraform/Helm/Kustomize, State-Handling, Modul-Struktur, Secrets, Provider-Versionen, Testing, Policy. Das ist wertvoll, aber nicht „kostenlos". Für kleine Teams wird IaC sonst schnell zum zweiten Produkt.
• Maintenance ist nicht optional: IaC reduziert Drift nur, wenn es konsequent der einzige Weg ist, Änderungen zu machen. In der Praxis kommen Hotfixes, manuelle Eingriffe, Provider-Updates, Breaking Changes und damit entsteht wieder Dokumentations- und Betriebsarbeit.
• Der Bus-Faktor verschiebt sich nur: Ohne klare Standards und Ownership landet das Wissen dann nicht mehr „im Kopf", sondern in einem Set aus Skripten/Modulen, das nur eine Person wirklich versteht.
• Mehr Freiheitsgrade = mehr Varianz: IaC erlaubt sehr viele Wege, „richtig" zu sein. In kleinen Teams führt das oft zu individueller Handschrift statt zu einem stabilen Standard – und damit zu genau dem Onboarding-Problem, das man eigentlich lösen wollte.

Heißt nicht: „IaC ist schlecht". Heißt nur: In KMU ist die Frage nicht „können wir IaC machen?", sondern „können wir IaC langfristig sauber betreiben – und ist das der beste Einsatz unserer knappen Zeit?"

Warum DevOps as a Service hier helfen kann

Eine DevOps-as-a-Service-Plattform verschiebt den Schwerpunkt von „wir bauen und pflegen unser eigenes IaC-Framework" hin zu „wir nutzen Standards, die bereits produktisiert sind".

Der praktische Nutzen für KMU:

• Standardisierte Deployments und Defaults: Weniger Entscheidungs- und Wartungsaufwand, weil zentrale Baseline-Patterns bereits vorgegeben sind.
• Weniger zu dokumentieren: Wenn Ingress, Observability, Security-Basics und Deployment-Mechanik über die Plattform standardisiert sind, bleibt für Teams vor allem Applikationswissen übrig.
• Ownership bleibt beim Team – ohne den Ops-Overhead: Teams können self-service arbeiten, ohne jedes Detail von Kubernetes/IaC selbst modellieren zu müssen.

In diesem Modell bleibt IaC als Prinzip erhalten (Versionierung, Nachvollziehbarkeit, Wiederholbarkeit), aber die Menge an selbst zu pflegendem „Plattform-Code" sinkt. Genau das ist für viele KMU der Unterschied zwischen „wir nehmen uns vor, zu dokumentieren" und „unsere Infrastruktur ist tatsächlich verständlich und wiederholbar".

Runbooks: klein, aktuell, nutzbar

Ein Runbook ist keine Dokumentation im klassischen Sinn. Es ist eine operative Anleitung für ein spezifisches Szenario: Was tun, wenn ein Pod crasht? Wie wird ein Rollback durchgeführt? Was sind die ersten Schritte bei einem Datenbankausfall?

Gute Runbooks sind kurz. Wenn ein Runbook mehr als eine Seite hat, ist es kein Runbook mehr, es ist ein Handbuch, das niemand im Ernstfall liest. Ziel ist: Jemand, der das System nicht von Grund auf kennt, kann das Problem in wenigen Minuten eingrenzen.

Was ein brauchbares Runbook enthält:

• Symptom: Woran erkenne ich das Problem?
• Ursachen: Was sind typische Auslöser?
• Sofortmaßnahmen: Was kann ich jetzt tun, um den Schaden zu begrenzen?
• Eskalation: Wen kontaktiere ich, wenn das nicht hilft?

Runbooks müssen dort leben, wo sie im Ernstfall gefunden werden, nicht in einem verschachtelten Wiki, sondern an einem bekannten, schnell erreichbaren Ort. Und sie müssen aktuell bleiben: Ein Runbook, das auf eine Konfiguration von vor zwei Jahren zeigt, ist schlimmer als gar keins.

Wie eine DaaS-Plattform den Dokumentationsaufwand reduziert

Ein häufig unterschätzter Hebel ist die Plattformebene selbst. Je mehr Komplexität durch eine Abstraktionsschicht verborgen wird, desto weniger gibt es zu dokumentieren.

Auf einer DevOps-as-a-Service-Plattform wie lowcloud deployen Entwickler Applikationen über standardisierte Schnittstellen. Die Frage „Wie ist unser Ingress konfiguriert?" stellt sich nicht mehr in der gleichen Form – das ist Aufgabe der Plattform. Was das Team dokumentieren muss, schrumpft auf die applikationsspezifischen Teile.

Das senkt nicht nur den Dokumentationsaufwand. Es erhöht auch die Qualität: Wenn das Team sich auf einen kleineren, klarer abgegrenzten Bereich konzentriert, ist es realistischer, dass die Dokumentation aktuell bleibt.

Darüber hinaus bringen managed Plattformen oft eingebaute Observability, Audit-Logs und nachvollziehbare Deployment-Historien mit. Das ersetzt keine Dokumentation, liefert aber Kontext, der sonst verloren geht.

Wissenstransfer bei Personalwechsel

Offboarding ist der Moment, an dem fehlende Dokumentation am teuersten wird. Eine Person verlässt das Unternehmen, und mit ihr gehen Entscheidungshintergründe, undokumentierte Konfigurationen und informelles Wissen über Systemzusammenhänge.

Kein Onboarding-Prozess der Welt kann das ausgleichen, wenn die Grundlagen fehlen. Was hilft, ist eine strukturierte Übergabe – nicht als PDF-Dokument kurz vor dem letzten Arbeitstag, sondern als kontinuierlicher Prozess.

Pair-Sessions, bei denen Wissen aktiv übertragen wird, sind effektiver als schriftliche Dokumentation allein. Kombiniert man das mit einer gut gepflegten IaC-Basis und aktuellen Runbooks, sinkt der Bus-Faktor spürbar, auch ohne dass jemand das System komplett von Grund auf neu erklären muss.

Ein einfacher Test: Könnte ein neues Teammitglied, ohne Rückfragen zu stellen, einen bestehenden Service deployen, einen Fehler eingrenzen und eine Konfigurationsänderung nachvollziehen? Wenn nein, habt ihr ein Dokumentationsproblem, unabhängig davon, wie viele Wiki-Seiten existieren.

Fazit: Dokumentation, die lebt

Wissensdokumentation in DevOps-Teams funktioniert nicht als separater Prozess. Sie muss in den Arbeitsablauf integriert sein – durch IaC, das den Systemzustand abbildet, durch lesbare Pipelines, durch kurze und aktuelle Runbooks.

Das Ziel ist nicht vollständige Dokumentation. Das Ziel ist, den Bus-Faktor auf ein akzeptables Niveau zu senken und Onboarding realistisch zu machen. Dafür braucht es keine umfangreichen Wikis. Es braucht Disziplin, klare Zuständigkeiten und eine Plattformebene, die Komplexität dort verbirgt, wo sie nicht vom Team selbst verwaltet werden muss.

Wer den Schritt zur DaaS-Plattform noch nicht gemacht hat: lowcloud ist eine Kubernetes-basierte Plattform, die Teams dabei hilft, Infrastrukturkomplexität zu reduzieren und sich auf das zu konzentrieren, was wirklich zählt – den eigenen Code.