Warum README-basiertes Engineering-Onboarding immer verrottet
Jede Engineering-README verrottet innerhalb von zwei Quartalen. Das Muster ist strukturell, nicht redaktionell, und sie noch härter neu zu schreiben ist die falsche Antwort.
- Zeit bis zur ersten gemergten PR
- 1 Woche
- Slack-DMs in Woche 1
- 1
- "Das sollte einfach laufen"
- 17 Mal
- Setup ohne fremde Hilfe
- 90 %
Die Kurzfassung.
Eine README ist ein einzelnes Dokument, das die kanonische Aufzeichnung jeder Etappe sein soll, die ein neuer Engineer zum Loslegen braucht. Das Muster scheitert immer auf dieselbe Weise: Es verrottet innerhalb von zwei Quartalen, und die Verrottung ist kein Schreibproblem. Sie ist ein Strukturproblem, weil ein einziges Dokument ein System nachhalten muss, das sich täglich ändert, zwischen Postgres-Versionen, Node-Versionen, SSL-Zertifikaten, VPN-Tunneln, Umgebungsvariablen und den vier Skripten in `bin/`, für die niemand verantwortlich ist. Die README härter zu überarbeiten kauft zwei saubere Wochen und liefert dann genau dieselbe Verrottung. Der Ausweg führt darüber, das Onboarding nicht länger als Dokument zu behandeln.
Die 17 Stellen, an denen die README lügt
Eine README lügt nicht aus Absicht. Sie lügt, weil jede Behauptung darin eine kürzere Halbwertszeit hat als der Review-Rhythmus des Dokuments. Der Satz "das sollte einfach laufen" tauchte siebzehnmal in der 2 400-Zeilen-README auf, die Stefan, Staff Engineer bei einer Berliner B2B-Observability-Plattform mit Trade-Republic-ähnlichem Lastprofil, im letzten Quartal ersetzt hat. Jedes Vorkommen markierte eine Stelle, an der dem Verfasser die Geduld für den Sonderfall ausgegangen war.
Der folgende Katalog stammt aus dem Diff einer realen Onboarding-Doku, Series-B-Team mit 65 Engineers.
| Art der Lüge | Typische Formulierung | Was tatsächlich stimmte | |
|---|---|---|---|
| 1 | Versionsdrift | "Node 18 installieren" | Node 20.6+ nötig, 18 scheitert an einem TypeScript-Decorator |
| 2 | Tool ersetzt | "make build ausführen" | Makefile in Q2 entfernt, durch ein Bun-Skript abgelöst |
| 3 | Schweigen zur Konfiguration | "Die Umgebungsvariablen ergänzen" | Vier undokumentierte Variablen blockieren den Dev-Server |
| 4 | Veraltetes Bildschirmfoto | Altes AWS-Console-Screenshot | Console neu gestaltet, der Button steht in einem anderen Menü |
| 5 | OS-Annahme | "Brew install Postgres" | Linux-Laptops brauchen apt, nicht brew, kein alternativer Pfad |
| 6 | Netzwerkannahme | "Das VPN sollte sich verbinden" | Die Corporate-Firewall blockt den Cert-Austausch unter macOS Sonoma |
| 7 | Falsche Reihenfolge | Schritte 4 und 5 vertauscht | Wer sie in der gelisteten Reihenfolge ausführt, korrumpiert die lokale DB |
| 8 | Berechtigungslücke | "Der Zugriff sollte stehen" | Neue Kollegen erhalten Zugriff am dritten Tag, nicht am ersten |
| 9 | Default-Branch | "main auschecken" | Der Default-Branch wurde vor sechs Monaten in trunk umbenannt |
| 10 | Pfad zu Secrets | "Aus dem Vault ziehen" | Der Vault-Pfad hat sich geändert, das CLI-Kommando braucht ein Flag |
| 11 | Halber Schritt | "Migrationen laufen lassen" | Das Migrationsskript braucht ein Flag, das die README weglässt |
| 12 | Schattenabhängigkeit | Keine Erwähnung von Redis | Ohne laufendes Redis crasht der Auth-Service stumm |
| 13 | Unbestätigtes "sollte" | "Das sollte einfach laufen" | Tut es nicht, der Fehler ist still und die Logs sind leer |
| 14 | Vendor-Wechsel | "Stripe-Testkeys" | Die Stripe-Sandbox wurde durch einen geforkten Mock ersetzt |
| 15 | bin-Skript | "bin/setup ausführen" | Das Skript wurde seit 2023 nicht mehr angefasst und setzt Python 2 voraus |
| 16 | Zerschossener Verweis | "Siehe Deploy-Leitfaden" | Der Deploy-Leitfaden wurde in einem Confluence-Aufräumen gelöscht |
| 17 | Browser-Sitzung | "Login auf localhost" | Das selbstsignierte Zertifikat wird von Chrome ohne manuelles Override geblockt |
make build ausführen"main auschecken"trunk umbenanntbin/setup ausführen"Jede einzelne Lüge ist klein. Die Summe macht aus der ersten Woche einer neuen Kollegin Archäologie. Die Story zur Engineering-Onboarding-Umstellung auf Leitfäden auf derselben Plattform hat das vermessen: Jede Neueinstellung lief in Woche 1 in rund sechs dieser Fallen.
Warum eine Neufassung der README nie hält
Drei Engineers hatten die README im Jahr vor Stefans Aufnahme bereits neu geschrieben. Jede Neufassung war für zwei Wochen exzellent. Dann verrottete sie. Das Muster hat nichts mit Disziplin oder rednerischem Talent zu tun. Es ist strukturell, und der Ausgang lässt sich vorhersagen, ohne das Team zu kennen.
Eine README hat zu jedem Zeitpunkt genau einen Autor. Die erste Neufassung passiert, sobald die Kosten der Verrottung sichtbar werden, etwa eine Woche Senior-DMs pro Neueinstellung. Jemand meldet sich freiwillig, blockiert zwei Tage, liefert ein gründliches Dokument und merged es. In der Woche danach kommt ein Tool-Update, ein Skript ändert sich, eine Umgebungsvariable wird ergänzt. Die ursprüngliche Autorin ist längst weiter. Die Änderung wird nicht zurückgespielt, weil das Editieren der Datei teurer ist als die Antwort in einer Slack-DM an die Person, die fragt. Die Verrottung beginnt in Woche drei.
Vergleichen Sie das mit der Art, wie Code aktuell bleibt. Code verrottet nicht im selben Tempo, weil der Build bricht, sobald Code veraltet. Die README ist aus Sicht des Builds ein reines Lese-Artefakt. Nichts schlägt fehl, wenn sie hinterherhinkt. Die NNGroup-Forschung dazu, warum Nutzer Webseiten scannen statt sie zu lesen, beschreibt das dominante Verhalten: Leser scannen, lesen nicht vollständig, und mit jeder falschen Behauptung verlieren sie weiter Vertrauen in das Dokument. Spätestens beim dritten Stolperer schließt die neue Kollegin die Datei und schreibt eine DM. Der Senior antwortet, weil Antworten schneller geht als Zeile 1 847 zu reparieren.
Die strukturelle Folgerung ist hart. Eine README ist das falsche Format, weil die Wartungskosten von einer Person getragen werden und die Fehlerkosten von einer anderen, und genau diese Asymmetrie macht die Verrottung unausweichlich. Eine Neufassung verändert die Asymmetrie nicht. Sie kauft zwei Wochen und stellt die Uhr zurück.
Der Pfad, der trägt, deckt Wartung und Änderung in einer Hand: Wer ein Werkzeug ändert, nimmt den betroffenen Schritt in zwei Minuten neu auf, ohne Doku-Sprint. Genau darauf ist der Aufnahmefluss der Chrome-Erweiterung gebaut.
Was die README ablöst
Was die README ablöst, sind zwölf kurze Leitfäden, einer pro Fehlermodus, aufgenommen von der Engineerin, die diesen Fehler zuletzt behoben hat. Die 2 400-Zeilen-README der Observability-Plattform wurde durch zwölf Leitfäden ersetzt. Die Zahlen lassen sich direkt ablesen: Die Zeit bis zur ersten PR fiel von drei Wochen auf eine. Slack-DMs in Woche 1 an die Senior-Engineers gingen von sechs auf eine pro Neueinstellung zurück. Setup ohne fremde Hilfe stieg von "fast nie" auf neunzig Prozent. Mit diesen Kennzahlen kann ein Staff Engineer oder Engineering Manager bei einem B2B-SaaS mit 50 bis 200 Engineers die Umstellung im Leadership belegen.
Die Struktur ist konkret. Ein Hauptleitfaden, dreiundzwanzig Schritte, läuft den Happy Path auf einem frischen Laptop ab. Jeder bekannte Fehlermodus, also die falsche Node-Version, das SSL-Zertifikat, die fehlenden Umgebungsvariablen, der VPN-Tunnel, die Postgres-Erweiterung, die vier bin/-Skripte, hat seinen eigenen kurzen Troubleshooting-Leitfaden. Der Hauptleitfaden verlinkt an genau dem Schritt auf den Troubleshooting-Leitfaden, an dem der Fehler typischerweise auftaucht. Die neue Kollegin scannt nicht mehr 2 400 Zeilen nach ihrem Fehler. Sie klickt durch.
Die Form jedes Leitfadens zählt. Schritte sind nummeriert. Jeder trägt einen Screenshot des aktuellen Bildschirms, keine ein Jahr alte Annäherung. Jeder enthält das exakte Kommando, keine paraphrasierte Variante. Die Erzählung erklärt, warum der Schritt existiert, nicht nur was er tut, weil neue Engineers Dokumenten misstrauen, die wie ein Kommando-Dump klingen. Die NNGroup-Forschung zum F-förmigen Lesemuster auf Webinhalten erklärt, warum dieses Format trägt: Leser scannen die ersten Wörter jeder Zeile, prüfen den Screenshot, gehen weiter. Die Granularität pro Schritt passt zum Scan-Verhalten.
Wenn sich ein Werkzeug ändert, wird nur der betroffene Schritt neu aufgenommen. Zwei Minuten, kein README-Refactor. Die Wartungskosten bleiben so niedrig, dass die Engineerin, die das Tool geändert hat, das Update tatsächlich macht. Die Fehlerkosten hören auf zu kompoundieren, weil die nächste Neueinstellung nie mehr in den veralteten Schritt läuft. Die vollständige Begründung lebt in dem Argument für Schritt-für-Schritt-Anleitungen.
Was es kostet, die README zu behalten
Die Kosten der README zahlt nicht ihr Verfasser. Sie zahlen die Senior-Engineers, die DMs beantworten, und die neuen Kollegen, deren erste PR um zwei Wochen rutscht. Genau das macht die Kosten unsichtbar für die Person, die das Dokument neu schreiben könnte. Die Buchführung ist falsch, und falsche Buchführung schützt schlechte Muster.
Rechnen Sie das auf 65 Engineers, vier Neueinstellungen pro Quartal, drei Wochen Ramp-up. Jede neue Kollegin erzeugt etwa sechs DMs in Woche 1 an Senior-Engineers. Jede DM kostet rund zwanzig Minuten, sobald Kontextwechsel mitgezählt werden. Das sind zwei Stunden Senior-Zeit pro Neueinstellung allein für die offensichtlichen Stolperer, vor jeder echten Setup-Hilfe. Vier Neueinstellungen pro Quartal mal zwei Stunden ergibt acht Stunden pro Quartal an Fragen, die ein Leitfaden hätte abfangen können.
Die Kosten pro Neueinstellung werden noch deutlicher. Zwei Wochen blockiertes Ramp-up bedeuten null gemergte PRs in den ersten vierzehn Tagen. Bei einem voll geladenen Kostenansatz von 200 000 $ pro Senior und Jahr (der konservative Wert für eine Series-B-Observability-Plattform), sind zwei Wochen Null-Output rund 7 700 $ pro Neueinstellung, also etwa 7 100 €, die das Unternehmen schluckt, weil die README verrottet ist. Mal vier Neueinstellungen pro Quartal landet die Jahresrechnung bei rund 123 000 $.
Die Kosten kompoundieren, weil sie in keiner Quartals-OKR auftauchen. Die Verrottungssteuer wird im Aggregat von der Engineering-Organisation gezahlt und taucht in keiner Einzelreview auf. Der Ausweg legt die Kosten auf die Person, die sie verhindern kann: Wer das Werkzeug ändert, repariert den Schritt, in denselben fünf Minuten. Genau das deckt der Team-Plan ab 12 $ pro Sitz ab, und die Kostenrechnung trägt sich praktisch immer im ersten Quartal.
Es gibt einen weicheren Posten. Eine Neueinstellung, die in Woche 1 zu vielen Lügen begegnet, startet mit der falschen Eichung. Sie lernt, dass Dokumentation unzuverlässig ist, dass Antworten über DMs an Senior-Engineers kommen, dass Prozesse verrotten. Diese Eichung ist schwer zurückzudrehen, sobald das Leadership später von genau diesen Engineers gute Doku verlangt.
Wann eine README das richtige Format bleibt
Eine README bleibt das richtige Format für Inhalte, die sich selten ändern und vollständig gelesen werden. Drei Fälle qualifizieren, der Rest gehört in aufgenommene Leitfäden.
Erster Fall, das Mission-Statement des Projekts. Was das System tut, was es nicht tut, wer es besitzt. Diese Information wechselt höchstens einmal pro Jahr. Eine Leserin scannt sie einmal und geht weiter. Ein README-Satz ist die richtige Form dafür.
Zweiter Fall, der Contributing-Leitfaden eines Open-Source-Projekts. Code-Stil, Branch-Konventionen, PR-Format auf GitHub, das Contributor License Agreement. Diese Regeln gelten für einmalige Beiträge von Personen, die nie im Team-Slack landen. Die Leserin hat keinen Zugang zu einem Capture-Workspace, keine Senior-Person zum DM-Schreiben, und braucht ein autarkes Textdokument, das direkt auf GitHub lesbar ist. Die README ist hier das richtige Vehikel.
Dritter Fall, der Architektur-Überblick auf hoher Ebene, das oberste Diagramm und die Beschreibung, welcher Service mit welchem spricht. Dieses Dokument ändert sich, wenn sich die Architektur ändert, also etwa ein- bis zweimal pro Jahr in einem stabilen System. Es wird zum Verstehen gelesen, nicht zum Ausführen, und das Lese-Einmal-Muster passt zum README-Format.
Alles, was sich häufiger als einmal pro Quartal ändert und zum Ausführen gelesen wird, gehört nicht hierher. Setup der Dev-Umgebung, Deploy-Fluss, On-Call-Runbook, Debugging-Muster mit Datadog oder Grafana, die vier Schattenabhängigkeiten, die den Auth-Service blockieren. All das verrottet im Tempo der unterliegenden Werkzeuge und profitiert von einer Aufnahme pro Schritt, die sich in zwei Minuten erneuern lässt. Diese Trennlinie hilft Personio-Engineering, GetYourGuide-SRE-Teams oder einer Plattform-Crew bei SAP gleichermaßen.
Eine zweite Lesung dieser Trennlinie lebt in Kunden-Onboarding-Workflow dokumentieren, wo dasselbe Argument in einer anderen Domäne entfaltet wird. Das strukturelle Problem ist identisch: Ein einzelnes Dokument kann keinen Prozess nachhalten, der sich schneller ändert, als er gepflegt wird. Der Ausweg trägt über Domänen hinweg.
Häufig gestellte Fragen.
- Wie lange dauert es, eine 2 400-Zeilen-README durch aufgenommene Leitfäden zu ersetzen?
Stefan, Staff Engineer bei der B2B-Observability-Plattform, hat den Hauptleitfaden mit dreiundzwanzig Schritten in rund vier Stunden aufgenommen, inklusive der Erzählung. Jeder der sechs Troubleshooting-Leitfäden für die einzelnen Fehlermodi brauchte etwa dreißig Minuten. Die gesamte Bearbeitungszeit blieb unter zwei Personentagen, schneller als jede der drei vorherigen README-Neufassungen, die das Team versucht hatte. Die vollen Zahlen stehen in der Story zum Engineering-Onboarding in Leitfäden.
- Wer pflegt die Leitfäden, wenn die ursprüngliche Autorin weiterzieht?
Wer das Werkzeug ändert, nimmt den betroffenen Schritt neu auf. Die Wartungskosten liegen bei zwei Minuten pro Änderung, niedrig genug, dass Engineers den Update wirklich tragen, statt ihn liegen zu lassen. Das Muster trägt, weil die Update-Kosten von derselben Person getragen werden, die den Bedarf ausgelöst hat, und damit verschwindet die Asymmetrie, die eine README zum Verrotten bringt. Ein Quartals-Review fängt vergessene Schritte auf, aber bei den niedrigen Pro-Schritt-Kosten ist das Quartalsereignis vor allem ein Sicherheitsnetz.
- Was ist mit Engineers, die lieber Text lesen als einen Leitfaden anzusehen?
Capture-Leitfäden sind keine Videos. Jeder Schritt besteht aus einem Screenshot plus einer geschriebenen Beschreibung, exportierbar als Markdown, HTML oder PDF. Wer überfliegen will, tut das genauso wie bei einer README, nur dass die Screenshots aktuell sind. Die Erzählung ist optional und rendert als Text, ausgerichtet zu jedem Schritt. Das Format optimiert für Scan-Leser, was die NNGroup-Forschung zu Lesbarkeit, Erkennbarkeit und Verständlichkeit als die tatsächliche Konsumweise technischer Doku belegt.
- Funktioniert das für Open-Source-Projekte mit externen Beitragenden?
Teilweise. Der Architektur-Überblick, der Contributing-Leitfaden und das Mission-Statement bleiben in der README, weil externe Beitragende keinen Zugang zu einem privaten Workspace haben. Das Setup der Dev-Umgebung lässt sich als PDF oder HTML exportieren und in das Repository committen, was externen Beitragenden dasselbe scanfreundliche Format gibt, ohne dass die Maintainer eine 2 400-Zeilen-Datei tragen müssen. Die Trennung läuft auf statische Inhalte in der README und ausführbare Workflows in aufgenommenen Leitfäden hinaus.
- Ab welcher Teamgröße lohnt sich die Umstellung?
Die Umstellung beginnt sich ab rund fünfzehn Engineers zu rentieren, sobald die DM-Steuer an die Seniors sichtbar genug wird, um eine Veränderung zu rechtfertigen. Darunter pflegt meist dieselbe Person die README, die sie auch liest. Oberhalb von fünfzig Engineers übersteigen die Unterbrechungskosten bei den Seniors, was das Format auffangen kann. Die Staff-Engineer- oder Engineering-Manager-Persona in einem B2B-SaaS zwischen 50 und 200 Engineers liefert den klarsten Hebel.
Bereit, Ihre Engineering-README durch zwölf aufgenommene Leitfäden zu ersetzen?
Capture nimmt das Setup einmal auf einem frischen Laptop auf, erzählt jeden Schritt mit und exportiert einen Leitfaden pro Schritt, der sich in zwei Minuten erneuert, sobald sich ein Werkzeug ändert. Die Zeit bis zur ersten PR fällt im oben dokumentierten Fall von drei Wochen auf eine.
Schritt-für-Schritt-Anleitungen: sechs Teams, eine Mechanik
Die erfahrene Person, die einen Workflow im Schlaf beherrscht, wird zum Engpass. Das Wiki verrottet. Das Loom-Video, das niemand ansieht, sammelt Staub. Schritt-für-Schritt-Anleitungen brechen dieses Muster in den sechs Teams, denen wir dabei produktiv zugesehen haben.
Kunden-Onboarding-Workflow dokumentieren in 2026
Die meisten Onboarding-Dokumente verlieren in acht Wochen ihren Wert, weil niemand sie neu aufnimmt, sobald die Oberfläche ein Update bekommt. Die Antwort ist nicht ein besserer Texter. Die Antwort ist eine Methode, die mit der Aufnahme beginnt und pro Auffrischung zehn Minuten kostet.
Die 12-Schritte-Regel: warum Länge das Scheitern von Dokumentation vorhersagt
Fast jedes Dokumentationsteam schreibt längere Leitfäden, als es sollte. Länge wirkt gegen Sie, und 12 Schritte ist die operative Obergrenze, oberhalb derer die Fertigstellungsquote zusammenbricht.
Nimm einen Workflow auf.
Kostenlose Chrome-Erweiterung. Keine Anmeldung erforderlich.