Eine 2.400-Zeilen-README durch zwölf Leitfäden ersetzt.
Ein Staff Engineer bei einer B2B-Observability-Plattform hat das Dev-Environment-Setup einmal aufgenommen. Die Time-to-First-PR neuer Kollegen ist von drei Wochen auf eine gefallen.
01
Die Onboarding-Engineer-Doku war eine README mit 2.400 Zeilen. Sie war gründlich und unzuverlässig. Manche Abschnitte verwiesen auf ein Build-System, das längst ersetzt war. Manche setzten eine OS-Version voraus, die in der Firma kein Laptop mehr fuhr. Der Satz "das sollte einfach laufen" tauchte siebzehnmal auf.
Jeder neue Engineer ist über dieselben Fehlschläge gestolpert: fehlende Postgres-Extension, falsche Node-Version, das SSL-Cert, das neu generiert werden musste, die vier Umgebungsvariablen, die niemand dokumentiert hatte. Jeder Fehlschlag wurde zur Slack-DM an einen Senior-Engineer. In Monat zwei einer Einstellungswelle haben Senior-Engineers die halbe Woche im Onboarding verbracht.
Die Lösung, die alle vorgeschlagen haben, lautete "die README neu schreiben". Drei Engineers hatten es im Vorjahr versucht. Jede Neufassung war zwei Wochen lang gut, dann veraltet. Die README ist verrottet, weil sie keinen Owner hatte. Die Kosten waren auf alle Senior-Engineers verteilt, die dieselben DMs beantworteten.
02
Das Setup wurde von Grund auf auf einem frischen Laptop aufgenommen, mit Capture im Hintergrund. Jeder Schritt und jeder Fehlschlag wurde dabei erläutert. Das Ergebnis war ein 23-schrittiger Leitfaden mit Screenshots des tatsächlich aktuellen Setups.
Der Leitfaden hat die README ersetzt. Neue Kollegen haben ihn an Tag eins geöffnet und durchgearbeitet. Die sechs bekannten Stolpersteine haben jeweils einen eigenen kurzen Troubleshooting-Leitfaden bekommen, verlinkt aus dem Haupt-Leitfaden.
Wenn sich ein Schritt ändert, ein Tool-Update oder eine neue Umgebungsvariable, wird genau dieser Schritt neu aufgenommen. Zwei Minuten Arbeit, keine README-Neufassung. Die onboarding-bezogenen Senior-Engineer-DMs sind von sechs pro Neueinstellung in Woche eins auf etwa eine gefallen. Diese eine ist meistens wirklich interessant.
03
- 01Das Setup live machen.
Frischer Laptop, Capture läuft mit. Jeden Schritt einschließlich der Fehlschläge erläutern.
- 02Fehlschläge erstklassig behandeln.
Jeder bekannte Stolperstein bekommt seinen eigenen kurzen Troubleshooting-Leitfaden.
- 03Aus einem Punkt verlinken.
Das Engineering-Wiki hat einen Eintrag: Hier starten.
- 04Schritt für Schritt pflegen.
Den betroffenen Schritt neu aufnehmen, wenn sich ein Tool ändert. Nicht den ganzen Leitfaden.
- 05Time-to-First-PR messen.
Onboarding-Erfolg wird an der Zeit bis zum ersten ausgelieferten PR gemessen.
04
Die Time-to-First-PR ist von drei Wochen auf eine gefallen. Senior-Engineers haben ihre erste Woche zurückgewonnen. Das Volumen der onboarding-bezogenen DMs ist um etwa 80% gefallen.
Das Muster hat sich verbreitet. Das On-Call-Runbook hat dieselbe Behandlung bekommen. Der PR-Review-Prozess wurde aufgenommen. Der Deploy-Ablauf wurde aufgenommen. Das Engineering-Wiki besteht jetzt aus zwölf Leitfäden, nicht aus 2.400 Zeilen meist veralteter README.
Einen Workflow aufzeichnen.
Kostenlose Chrome-Erweiterung. Keine Anmeldung erforderlich.
Customer Success hat den Onboarding-Zoom abgelöst.
45-Minuten-Termine wurden zu 12-Minuten-Leitfäden. Das Gebiet ist um 80% gewachsen, ohne neue Stellen.
Operations hat die SOP-Bibliothek vor dem Audit neu aufgebaut.
Einundzwanzig Prozesse, von ihren Ownern aufgenommen. SOC 2 zwei Wochen früher abgeschlossen.
IT hat Tier-1-Tickets um ein Drittel gesenkt.
Zwanzig Wiederholungsfragen, zwanzig Leitfäden, acht Wochen. Die Montagnachmittage sind zurück.