Dokumente und Runbooks lesen die Leute wirklich.

Jedes Team sagt, dass es Dokumentation schätzt. Dann öffnen Sie das Wiki und finden Seiten, die zuletzt vor drei Jahren aktualisiert wurden, Anweisungen für Server, die nicht mehr existieren, und eine Seite mit dem Titel "TODO: schreiben Sie dies" von jemandem, der 2023 gegangen ist.

Schlechte Dokumentation ist schlimmer als gar keine, weil die Leute ihr vertrauen und ihnen folgen. Aber gute Dokumentation ist eines der höchsten Hebel, die ein DevOps-Team produzieren kann. So überlebt Wissen Urlaub, Krankheitsurlaub und Menschen, die weiterziehen.

Hier ist, wie man Dokumente schreibt, die nützlich bleiben.

Warum verrottet ein Doktor ?

• Sie leben weit weg vom Code. Ein Wiki, auf das niemand schaut, wenn sie das System ändern.
• Niemand besitzt sie. Jeder kann bearbeiten, also fühlt sich niemand verantwortlich.
• Sie sind nicht Teil der Arbeit. Dokumente sind "extra", später fertig, was bedeutet nie.
• Sie sind zu lang. Die Leute lesen es nur unbedingt, übersehen den wichtigen Teil und hören auf zu lesen.

Die Ärzte wohnen neben dem Code .

Docs-as-code (Dokumenten als Code) bedeutet, die Dokumentation wie Code zu behandeln:

• Schriftlich Markdown, in der gleiche Speicher Wie der Code, den sie beschreiben.
• Die gleiche Zuganfrage Wenn der Code ändert.
• Überarbeitet Wie Code.
• Automatisch veröffentlicht durch eine Pipeline zu einer netten Website.

Werkzeuge, die das einfacher machen:

• MkDocs mit der Material Thema: einfach, schön, sehr beliebt für technische Dokumente.
• Schlachthocker: React-basiert, ideal für größere Dokumentationsstandorte.
• TechDocs hinter den Kulissen: stellt MkDocs-Dokumente aus jedem Repository in Ihrem Entwicklerportal.
• Einfach README.md Dateien, die GitHub und GitLab gut rendern.

Eine Pull-Request-Vorlage mit einem Kontrollkästchen "Dokumentation aktualisiert (oder nicht benötigt) " ist ein kleiner Schubs, der sehr hilft.

Der beste Zeitpunkt, um die Dokumentation zu aktualisieren, ist in derselben Pull-Anfrage, die sie falsch macht.

Eine Runbook-Vorlage

Die Runbooks sind die wichtigsten Dokumente für Operationen. Wenn um 3 Uhr ein Alarm ausgelöst wird, braucht der Diensttechniker schnell Antworten, nicht Prosa.

Meine Vorlage:

# Alert: CheckoutHighErrorRate

## What it means
More than 2% of checkout requests return 5xx errors over 5 minutes.

## Impact
Customers can't complete purchases. Revenue impact. Treat as SEV2 or higher.

## Check
1. Dashboard: [Checkout overview](https://grafana.example.com/d/checkout)
2. Recent deployments: `kubectl rollout history deploy/checkout -n shop`
3. Errors by endpoint: [Logs query](https://grafana.example.com/explore?...)
4. Payment provider status: https://status.paymentprovider.example

## Common causes and fixes
- **Bad deployment** → roll back: revert the commit in the GitOps repo
  (or `kubectl rollout undo deploy/checkout -n shop` in an emergency).
- **Payment provider outage** → switch to backup provider via feature flag `payments.fallback`.
- **Database connection exhaustion** → check `orders-db` connections dashboard; scale checkout down
  temporarily or restart the connection pooler.

## Escalation
- Checkout team: @checkout-oncall
- Database: @dba-oncall
- Incident commander for SEV1: use `/incident declare`

## Last reviewed
2026-09-15 by @desly

Grundprinzipien: direkt verlinken Die Datenbank wird in den folgenden Bereichen erstellt: Kommandos für Kopieren und Einfügen, Liste häufige Ursachen zuerstUnd sagen: wen zu rufen- Ich weiß . Und verknüpfen Sie das Fahrbuch mit der Alarmanmeldung selbst.

Festlegung von Entscheidungen

Sechs Monate nach einer Entscheidung erinnert sich niemand, warum sie getroffen wurde. "Warum verwenden wir Loki und nicht Elasticsearch?" "Warum ist dieser Dienst in einem eigenen Cluster?" Ohne Aufzeichnungen wiederholen Teams entweder alte Debatten oder rückgängig machen zufällig gute Entscheidungen.

Architekturentscheidungsunterlagen (ADR) Lösen Sie das. Eine ADR ist ein kurzes Dokument, in der Regel eine Seite, das im Repository gespeichert wird:

# ADR-012: Use Gateway API instead of Ingress for new services

## Status
Accepted (2026-05-04)

## Context
ingress-nginx was retired in March 2026. We need a supported way to route traffic.

## Decision
New services use Gateway API with Envoy Gateway. Existing Ingress resources
are migrated by end of Q3.

## Consequences
+ Supported, portable API with role separation.
- Teams need to learn HTTPRoute; some annotations need manual migration.

Nummeriert, abgekürzt, nie gelöscht (übersetzte ADRs sind als solche gekennzeichnet). Werkzeuge wie Adr-Tools oder Log4brains Hilfe, aber ein Ordner mit Markdown-Dateien funktioniert perfekt.

Frisch halten

• Eigentümer: Jedes Dokument oder jede Mappe hat ein Besitzteam (CODEOWNERS arbeitet auch für Dokumente).
• "Letzt überprüft" auf Laufbücher, wobei regelmäßig überprüft wird (z. B. vierteljährlich oder nach jedem Vorfall, bei dem das Laufbericht verwendet wurde).
• Aktualisierung nach VorfällenEin postmortem Aktionspunkt ist oft "Update the runbook".
• Aggressiv löschenVeraltete Dokumente sind gefährlich. Archivieren oder löschen.
• Sei kurz.Eine klare Seite schlägt zehn vage.
• Erstellen Sie es durchsuchbarEine Dokumentationsseite mit Suchfunktion oder ein Portal wie Backstage.

Ein paar Worte über KI

KI-Tools sind großartig beim Entwerfen von Dokumentation: Zusammenfassung einer Codebasis, Umwandlung einer Ereigniszeitlinie in ein Runbook, Erläuterung einer komplexen Konfiguration. Verwenden Sie sie für erste Entwürfe. Aber ein Mensch, der das System kennt, muss jeden Schritt überprüfen, denn ein falsches Fahrplan um 3 Uhr morgens ist schlimmer als gar nichts.

Also, wo fange ich an?

Schreiben Sie Runbooks für Ihre fünf häufigsten Warnungen, mit der Vorlage oben, und verknüpfen Sie sie von den Warnungen. Dann eröffnen Sie einen ADR-Ordner und schreiben Sie den ersten Eintrag über die nächste Entscheidung, die Ihr Team trifft.

Meine Meinung: Dokumentation ist ein Geschenk für Ihr zukünftiges Selbst und Ihre Kollegen. Halten Sie es kurz und wahr.

Desly