Wissen, das nur in Köpfen existiert, ist ein Betriebsrisiko. Spätestens bei Urlaub, Personalwechsel oder einem Incident um 03:00 Uhr zeigt sich, ob Systeme „nur gebaut“ oder wirklich betreibbar sind. Gute Dokumentation reduziert Abhängigkeiten, verkürzt Einarbeitung und macht Abläufe wiederholbar – ohne dass jedes Team das Rad neu erfindet.

In diesem Artikel geht es um technische Dokumentation und Runbooks, die im Alltag funktionieren: Was muss rein (und was nicht), wie bleibt es aktuell, und wie verbindet man Dokumentation sinnvoll mit Monitoring, Incident‑Prozessen und Übergaben.

Warum Dokumentation in IT-Organisationen scheitert

Die häufigsten Gründe sind nicht fehlende Tools, sondern fehlende Klarheit:

Unklare Zielgruppe: „für alle“ heißt oft „für niemand“.

Zu viel oder zu wenig Detail: Entweder Handbuchroman oder Bullet‑Point ohne Kontext.

Keine Ownership: Dokumentation ist „Aufgabe von irgendwem“.

Nicht im Prozess verankert: Änderungen passieren im Code, Docs bleiben stehen.

Eine pragmatische Leitfrage: „Welche Information brauche ich, um den Service sicher zu betreiben, zu verändern und im Notfall wiederherzustellen?“

Welche Dokumentation wirklich Wert stiftet

Nicht jede Seite ist gleich wichtig. Für viele Teams reichen wenige, aber hochwertige Artefakte:

Service‑Steckbrief (pro Service/Komponente)

Zweck und Business‑Kritikalität

Owner/Verantwortliche, On‑Call Kontakt

Abhängigkeiten (DB, Queue, externe APIs)

Deploy‑Prozess und Rollback/Disable‑Strategie

SLO/SLA‑Ziele und wichtigste Dashboards

Passend dazu:

Monitoring & Observability

SLA, SLO & Incident Response

Architektur- und Integrationsdokumentation

Minimal, aber klar:

Kontextdiagramm (Systemgrenzen, externe Systeme)

Datenflüsse (wer schreibt/liest was?)

Security‑Zonen und Trust Boundaries

Betriebsabhängigkeiten (Secrets, Zertifikate, Jobs)

ADRs (Architecture Decision Records)

ADRs dokumentieren Entscheidungen, nicht „alles“. Ein gutes ADR beantwortet:

Problem/Context

Entscheidung + Alternativen

Konsequenzen (Trade‑offs)

Datum, Owner, Revisionspfad

ADRs verhindern das „Warum ist das so?“‑Pingpong und sind besonders wertvoll bei Onboarding und Audit‑Fragen.

Runbooks: der Kern für On‑Call und Betrieb

Runbooks sind Schritt‑für‑Schritt‑Anleitungen für wiederkehrende Tätigkeiten und typische Incidents. Sie sind dann gut, wenn sie auch unter Stress funktionieren.

Typische Runbook‑Kategorien

Incident‑Runbooks (z. B. „Fehlerrate steigt“, „Queue staut“, „DB Read‑Only“)

Betriebsaufgaben (Backup/Restore, Rotation von Zertifikaten, Skalierung)

Deployment‑/Rollback‑Runbooks

Onboarding/Offboarding‑Checklisten

DR‑ und Failover‑Prozeduren (inkl. Tests)

Struktur, die sich bewährt hat

Wann anwenden? (Trigger/Alerts/Symptome)

Risiko/Impact (worauf achten, was nicht tun)

Voraussetzungen (Zugänge, Rechte, Tools)

Schritte (konkret, copy‑paste‑fähig, mit erwarteten Outputs)

Verifikation (Woran erkenne ich Erfolg? Welche Metrik muss sich ändern?)

Fallback/Eskalation (wenn es nicht wirkt: wohin, welche Daten mitgeben)

Wichtig: Runbooks sollten immer auf Observability‑Signale verweisen (Dashboard‑Links, Log‑Queries). Ohne das bleibt Troubleshooting ein Ratespiel.

Docs as Code vs. Wiki: eine pragmatische Entscheidung

Beide Ansätze können funktionieren – entscheidend ist, dass Dokumentation im Alltag gepflegt wird.

Docs as Code (Git‑basiert)

Vorteile:

Versionierung, Reviews, Nachvollziehbarkeit

Nähe zum Code (Änderungen werden gemeinsam gemerged)

Automatisierbar (Build, Link‑Checks, Veröffentlichung)

Typische Tools:

MkDocs: https://www.mkdocs.org/

Docusaurus: https://docusaurus.io/

Wiki/Knowledge Base

Vorteile:

niedrige Hürde für „schnelle“ Inhalte

kollaborativ, gut für Prozess-/Organisationswissen

Beispiele:

Confluence: https://www.atlassian.com/software/confluence

Notion: https://www.notion.so/

In der Praxis ist ein Mix häufig sinnvoll: Service‑kritische Docs „as code“, organisatorische Inhalte im Wiki – mit klarer Abgrenzung.

Dokumentation aktuell halten: Prozesse statt Appell

Definition of Done erweitern

„Done“ heißt: Betrieb und Wissen sind mitgedacht. Beispiele:

Runbook aktualisiert, wenn Alert/Incident‑Handling geändert wurde

Architekturdiagramm aktualisiert, wenn Schnittstellen geändert wurden

ADR geschrieben, wenn eine relevante Entscheidung getroffen wurde

Review‑Rhythmus und Ownership

Owner pro Service‑Doc (nicht „Team allgemein“)

quartalsweise Review‑Slots für kritische Services

nach Incidents: Runbook‑Verbesserung als Postmortem‑Outcome

„Executable“ Dokumentation

Wo möglich, reduzieren automatisierte Runbooks Tippfehler und erhöhen Geschwindigkeit:

Ansible Playbooks statt reiner Klickpfade

Skripte/Commands als geprüfte Snippets

standardisierte Queries (z. B. Log‑Filter, PromQL‑Beispiele)

Verbindung zu Übergabe und Training

Dokumentation entfaltet ihren Wert besonders dann, wenn sie Teil einer strukturierten Übergabe und Einarbeitung ist:

Strukturierte Übergabe

Hands-on Training

Mini-Vorlage: Runbook in 12 Zeilen

Wenn Teams mit Runbooks starten, hilft eine kurze Standardvorlage. Beispiel (als Mindeststandard):

Zweck/Trigger (welcher Alert, welches Symptom?)

Impact (was ist betroffen, wie kritisch?)

Voraussetzungen (Zugänge, Rechte, Tools)

Schritte (copy‑paste‑fähig, inkl. erwarteter Outputs)

Verifikation (welche Metrik/Log bestätigt Erfolg?)

Rollback/Fallback (wenn Schritt X nicht wirkt)

Eskalation (wen informieren, welche Daten mitgeben?)

Mit dieser Struktur sind Runbooks schnell schreibbar und trotzdem im Incident nutzbar. Später kann man sie erweitern (z. B. „Failure Modes“, Links zu Dashboards, Testdaten).

FAQ

Wiki oder Docs as Code – was ist „besser“?

Für servicekritische Inhalte ist Docs‑as‑Code oft stabiler (Reviews, Versionierung, Nähe zum Code). Für organisatorische Inhalte kann ein Wiki sinnvoll sein. Entscheidend ist die Abgrenzung und Ownership.

Wie hält man Dokumentation aktuell?

Indem sie Teil des Prozesses ist: Definition of Done, regelmäßige Reviews und Postmortem‑Outcomes, die Runbooks konkret verbessern. „Dokumentation nach Projektende“ funktioniert selten.

Was ist das Minimum, das jedes Team haben sollte?

Service‑Steckbrief, 3–5 Runbooks für häufige Incidents/Tasks, sowie Links zu Dashboards/Logs. Alles Weitere kann iterativ wachsen.

Fazit

Gute Dokumentation ist kein Nebenprodukt, sondern Teil von Zuverlässigkeit. Mit wenigen, klaren Artefakten (Service‑Steckbrief, Runbooks, ADRs), verankert in Reviews und Definition of Done, sinkt der Bus‑Factor, On‑Call wird ruhiger und Änderungen werden planbarer – weil Wissen nicht mehr „implizit“ bleibt.

Dokumentation & Runbooks: Wissen nachhaltig sichern