Onboarding-Dokumentation: der Weg von einer frischen Maschine zu einer gemergten Änderung

Ziel

Eine neue Person erreicht eine erste gemergte Änderung, indem sie ausschliesslich den Dokumenten folgt, und die Dokumente verbessern sich mit jeder neuen Person, statt zwischen den Ankünften zu veralten.

Voraussetzungen

Ein README, das die Grundfragen beantwortet; ein Pool kleiner, gelabelter erster Aufgaben; ein benannter Owner für den Onboarding-Weg. Das zitierte Google-Kapitel argumentiert, dass die meisten Projekte ein «Hello World»-Dokument verdienen, das nichts voraussetzt und die Ingenieurin dazu bringt, etwas Echtes geschehen zu lassen, und dass der beste Zeitpunkt für ein solches Tutorial der ist, an dem man einem Team neu beitritt. Diátaxis (zitiert) klassifiziert dieses Dokument als Tutorial: lernorientiert, eine praktische Aktivität auf ein erreichbares Ziel hin.

Schritte

1. Den Weg als eine einzige nummerierte Abfolge schreiben, mit dem Endzustand ganz oben: «am Ende hast du eine Änderung geöffnet, überprüft und gemergt». Alles, was nicht auf diesem Weg liegt, gehört woanders hin und wird verlinkt.
2. Jeden Einrichtungsschritt als exakten Befehl mit erwarteter Ausgabe angeben sowie eine Prüfung, die die neue Person ausführen kann («die Testsuite meldet N bestanden»). Voraussetzungen (Konten, Berechtigungen, Hardware) vor Schritt eins auflisten, nicht erst auf halbem Weg entdecken lassen.
3. Eine reine Link-Übersichtsseite bereitstellen: Repositories, Umgebungen, wer wofür zuständig ist, das Glossar, die Kommunikationskanäle, der Release-Kalender. Kein Fliesstext, der veraltet.
4. Auf den Pool der ersten Aufgaben und das Label verweisen, das geeignete Aufgaben kennzeichnet; das Dokument beschreibt, wie man eine beansprucht und was «erledigt» hier bedeutet.
5. Die neue Person verpflichten, während der ersten Tage ein Protokoll jedes Stolperns, jeder Frage und jedes Workarounds zu führen und das Protokoll als erste eigene Beiträge in Pull Requests gegen die Onboarding-Dokumente zu verwandeln.
6. Dem Weg einen Owner und ein Datum der letzten Überprüfung geben; ihn bei Ankunft einer neuen Person oder in festem Intervall von einer sauberen Maschine aus erneut durchlaufen und Schritte löschen, die nicht mehr gelten. Das zitierte Kapitel beschreibt Aktualitätsdaten und das Markieren veralteter Dokumente, statt sie stehen zu lassen.
7. Eine Agenten-Variante desselben Wegs pflegen: nicht-interaktive Befehle, keine Schritte, die einen Browser-Login verlangen, wo stattdessen ein Token bereitgestellt werden kann, sowie eine ausdrückliche Liste von Handlungen, die der Agent nicht vornehmen darf (deployen, löschen, Personen kontaktieren).

Erwartetes Ergebnis

Die Zeit von der Ankunft bis zur ersten gemergten Änderung wird durch den Weg begrenzt, nicht durch die Verfügbarkeit einer Kollegin; die Onboarding-Dokumente sind die im Repository am häufigsten korrigierten Seiten.

Grenzen und Prüfbasis

Der Weg deckt die Mechanik ab, nicht das Urteilsvermögen; das Verständnis der Domäne kommt weiterhin aus der Zusammenarbeit mit Menschen und aus den Designdokumenten. Umgebungen, die sich nicht auf einer sauberen Maschine reproduzieren lassen (lizenzierte Tools, eingeschränkte Daten), brauchen einen angegebenen Ausweichweg. Zur Onboarding-Dauer wird keine Messung beansprucht.