Een README van 2.400 regels vervangen door twaalf gidsen.
Een staff engineer bij een B2B observability-platform nam de inrichting van de dev-omgeving één keer op. De tijd tot eerste PR voor nieuwe medewerkers zakte van drie weken naar één.
01
Het inwerkdocument voor engineers was een README van 2.400 regels. Het was grondig en onbetrouwbaar. Sommige stukken verwezen naar een buildsysteem dat was vervangen. Sommige gingen uit van een OS-versie die op geen enkele laptop in het bedrijf nog draaide. De zin "dit zou gewoon moeten werken" stond er zeventien keer in.
Elke nieuwe engineer liep tegen dezelfde mislukkingen aan: een ontbrekende Postgres-extensie, de verkeerde Node-versie, het SSL-certificaat dat opnieuw aangemaakt moest worden, de vier omgevingsvariabelen die niemand had gedocumenteerd. Elke mislukking werd een Slack-DM aan een senior engineer. In maand twee van een aanwervingsgolf besteedden senior engineers de helft van hun week aan inwerken.
De oplossing die iedereen voorstelde was "de README herschrijven". In het jaar daarvoor hadden drie engineers het geprobeerd. Elke herschrijving was twee weken goed en verouderde daarna. De README verouderde omdat niemand er eigenaar van was. De kosten waren verdeeld over elke senior engineer die dezelfde DM's opving.
02
De inrichting werd vanaf nul opgenomen op een nieuwe laptop, met Capture aan. Elke stap en elke mislukking werd toegelicht. De oplevering was een gids van drieëntwintig stappen met schermafbeeldingen van de werkelijke huidige inrichting.
De gids verving de README. Nieuwe medewerkers openden hem op dag één en werkten zich erdoorheen. De zes bekende mislukmodi kregen elk een eigen korte probleemoplossingsgids, gelinkt vanuit de hoofdgids.
Wanneer een stap verandert (een tool-update, een nieuwe omgevingsvariabele), wordt alleen die stap opnieuw opgenomen. Twee minuten werk, geen herschrijving van de README. Inwerk-DM's aan senior engineers zakten van zes per nieuwe medewerker in week één naar ongeveer één. Die ene gaat meestal over een echt interessant geval.
03
- 01Doe de inrichting live.
Nieuwe laptop, Capture aan. Lichte elke stap toe, ook de mislukkingen.
- 02Behandel de mislukkingen als eersteklas burgers.
Elke bekende mislukmodus krijgt een eigen korte probleemoplossingsgids.
- 03Vanaf één plek gelinkt.
De engineering-wiki heeft één ingang: Begin hier.
- 04Onderhoud per stap.
Neem alleen de geraakte stap opnieuw op als een tool verandert. Niet de hele gids.
- 05Volg de tijd tot eerste PR.
Het succes van het inwerken meet je aan de tijd tot de eerste verzonden PR.
04
De tijd tot eerste PR zakte van drie weken naar één. Senior engineers kregen hun eerste week terug. Het volume aan inwerk-DM's zakte ongeveer 80%.
Het patroon verspreidde zich. Het on-call-runbook kreeg dezelfde behandeling. Het PR-reviewproces is opgenomen. De deploy-flow is opgenomen. De engineering-wiki bestaat nu uit twaalf gidsen, niet uit 2.400 regels grotendeels verouderde README.
Neem één workflow op.
Gratis Chrome-extensie. Geen registratie nodig.
Klantsucces zette de Zoom-inwerksessie aan de kant.
Gesprekken van 45 minuten werden gidsen van 12 minuten. Het gebied groeide 80% zonder extra mensen.
Operations bouwde de bibliotheek met werkinstructies opnieuw op voor de audit.
Eenentwintig processen, opgenomen door hun eigenaars. SOC 2 sloot twee weken eerder.
IT verlaagde Tier 1 tickets met een derde.
Twintig terugkerende vragen, twintig gidsen, acht weken. De maandagmiddagen kwamen terug.