Waarom README-gebaseerde engineering-onboarding altijd rot
Elke onboarding-README rot binnen twee kwartalen. Het defect is structureel, niet redactioneel, en harder herschrijven lost niets op.
- Tijd tot eerste gemergde PR
- 1 week
- Slack-DMs in week 1
- 1
- "Het zou moeten werken"
- 17 keer
- Setup zonder hulp afgerond
- 90%
De korte versie.
Een README is een enkel document dat de canonieke vastlegging probeert te zijn van elke stap die een nieuwe engineer nodig heeft om aan de slag te gaan. Het faalpatroon is heel specifiek: hij rot binnen twee kwartalen, en die rot is geen schrijfprobleem. Het is een structureel probleem, omdat één bestand een systeem moet bijhouden dat dagelijks verandert, tussen Postgres-versies, Node-versies, SSL-certificaten, VPN-tunnels, omgevingsvariabelen en de vier scripts in `bin/` waar niemand eigenaar van is. De README harder herschrijven levert twee schone weken op en daarna komt dezelfde rot terug. De uitweg is om onboarding niet langer als een document te behandelen.
De 17 plekken waar de README liegt
Een README liegt niet met opzet. Hij liegt omdat elke bewering een halfwaardetijd heeft die korter is dan de reviewcadens van het bestand. De zin "het zou moeten werken" verschijnt zeventien keer in de README van 2.400 regels die Sjoerd, staff engineer bij een B2B observability-platform, vorig kwartaal heeft vervangen. Elke instantie markeerde een plek waar de auteur het geduld voor het randgeval had verloren.
De catalogus hieronder komt uit de diff van een echte onboarding-doc bij een Series B-team van vijfenzestig engineers.
| Type leugen | Typische zin | Wat er feitelijk speelde | |
|---|---|---|---|
| 1 | Versie-drift | "Installeer Node 18" | Node 20.6 minimaal vereist, 18 crasht op een TypeScript-decorator |
| 2 | Tool vervangen | "Voer make build uit" | Makefile in Q2 verwijderd, vervangen door een Bun-script |
| 3 | Stilte over config | "Voeg de omgevingsvariabelen toe" | Vier ongedocumenteerde vars blokkeren de dev-server |
| 4 | Verouderde screenshot | Oude AWS-console-screenshot | Console herontworpen, de knop staat in een ander menu |
| 5 | OS-aanname | "Brew install Postgres" | Op Linux is apt nodig, geen alternatief beschreven |
| 6 | Netwerk-aanname | "VPN zou moeten verbinden" | De corp-firewall blokkeert de cert-uitwisseling op macOS Sonoma |
| 7 | Volgordefout | Stap 4 en 5 zijn omgewisseld | De vermelde volgorde corrumpeert de lokale database |
| 8 | Permissiegat | "Je zou toegang moeten hebben" | Nieuwe collega's krijgen toegang op dag drie, niet dag één |
| 9 | Branch-drift | "Check main uit" | De default-branch werd zes maanden geleden hernoemd naar trunk |
| 10 | Secrets-pad | "Haal het uit de vault" | Het pad is verschoven, de CLI vereist een extra flag |
| 11 | Halve stap | "Draai de migraties" | Het migratiescript heeft een flag nodig die de README weglaat |
| 12 | Schaduw-dependency | Geen vermelding van Redis | Zonder Redis crasht de auth-service in stilte |
| 13 | Onbevestigd "zou moeten" | "Het zou moeten werken" | Nee, de fout is stil en de logs zijn leeg |
| 14 | Vendor-wissel | "Stripe test-keys" | De Stripe-sandbox is vervangen door een interne mock |
| 15 | Bin-script | "Voer bin/setup uit" | Het script is sinds 2023 niet aangeraakt en gaat uit van Python 2 |
| 16 | Doorverwijzing kapot | "Zie de deploy-handleiding" | De handleiding is bij een Confluence-opruiming verwijderd |
| 17 | Browsersessie | "Login op localhost" | Het zelfondertekende cert wordt door Chrome geblokkeerd zonder handmatige override |
make build uit"main uit"trunkbin/setup uit"Elke leugen is klein. De optelsom maakt de eerste week van een nieuwe collega tot een archeologisch project. Het verhaal over engineering-team-documentatie bij hetzelfde platform heeft het gemeten: elke nieuwe collega liep in week één tegen ongeveer zes van deze fouten aan.
Waarom de README herschrijven nooit blijft hangen
Drie engineers hadden in het jaar voor het werk van Sjoerd al geprobeerd de README te herschrijven. Elke herschrijving was prima gedurende twee weken. Daarna rotte hij. Het patroon heeft niets te maken met discipline of schrijftalent. Het is structureel, en je kunt het falen voorspellen zonder het team te kennen.
Een README heeft op elk moment één auteur. De eerste herschrijving komt op gang wanneer de kosten van de rot zichtbaar worden (een week aan Slack-DMs naar seniors per nieuwe collega). Iemand meldt zich vrijwillig, blokkeert twee dagen, levert iets degelijks op. De PR wordt gemergd. De week erna gaat een tool een versie omhoog, een script verandert, een omgevingsvariabele wordt toegevoegd. De oorspronkelijke auteur is met iets anders bezig. De aanpassing wordt niet teruggedragen, omdat het bewerken van het bestand duurder is dan het antwoord typen in een Slack-DM aan wie er om vraagt. De rot start opnieuw in week drie.
Vergelijk dit met hoe code actueel blijft. Code rot niet in hetzelfde tempo, omdat de build breekt zodra de code afdrijft. Vanuit het perspectief van de build is de README een artefact dat alleen gelezen wordt. Er breekt niets als hij achterop raakt. Het onderzoek van NNGroup over waarom webgebruikers scannen in plaats van lezen beschrijft het dominante patroon: lezers scannen, ze lezen niet integraal, en ze geven een document steeds minder krediet bij elke onjuiste bewering. Bij de derde leugen sluit de nieuwe collega het bestand en opent een DM. De senior antwoordt, omdat antwoorden sneller is dan regel 1.847 herschrijven.
De structurele conclusie is hard. Een README is het verkeerde formaat omdat de onderhoudskosten door één persoon worden gedragen en de faalkosten door een andere, en die asymmetrie maakt rot onvermijdelijk. Herschrijven verandert die asymmetrie niet. Het koopt twee weken en zet de teller op nul.
De route die wel werkt, legt de onderhouder gelijk aan de persoon die de tool wijzigt: wie een script aanpast, neemt de betreffende stap in twee minuten opnieuw op, zonder doc-sprint. Dat is precies waar de Chrome-extensie van Capture om gebouwd is.
Wat een README vervangt
Wat een README vervangt, zijn twaalf korte gidsen, één per faalmodus, opgenomen door de engineer die dat probleem het laatst heeft opgelost. De README van 2.400 regels bij het observability-platform werd vervangen door twaalf gidsen. De cijfers laten zich direct lezen: de tijd tot de eerste gemergde PR daalde van drie weken naar één. De Slack-DMs naar seniors in week één gingen van zes naar één per nieuwe collega. Het percentage setups dat zelfstandig wordt voltooid, sprong van "bijna nooit" naar negentig procent. Met deze metrieken kan een staff engineer of engineering manager bij een B2B SaaS, vijftig tot tweehonderd engineers, de overstap richting leadership verdedigen.
De structuur is precies. Eén hoofdgids van drieëntwintig stappen doorloopt het standaardpad op een verse laptop. Elke bekende faalmodus (de verkeerde Node-versie, het SSL-cert, de ontbrekende env-vars, de VPN-tunnel, de Postgres-extensie, de vier bin/-scripts) krijgt een eigen korte troubleshooting-gids. De hoofdgids verwijst naar de juiste troubleshooting-gids op de exacte stap waar de fout typisch verschijnt. De lezer scant niet langer 2.400 regels op zoek naar zijn fout. Hij klikt door.
De vorm van elke gids telt. Stappen zijn genummerd. Elke stap heeft een screenshot van het huidige scherm, niet een benadering van een jaar geleden. Elke stap toont het exacte commando, geen herformulering. De voice-over legt uit waarom de stap bestaat, niet alleen wat hij doet, omdat een nieuwe collega stopt met geloven in een document dat zich leest als een commando-dump. Het NNGroup-onderzoek over het F-patroon bij webteksten verklaart waarom dit format werkt: lezers nemen de eerste woorden van elke regel mee, kijken naar de screenshot, gaan verder. De stap-granulariteit sluit aan bij dat scangedrag.
Wanneer een tool verandert, wordt alleen de betreffende stap opnieuw opgenomen. Twee minuten, geen README-revisie. De onderhoudskost blijft laag genoeg dat de engineer die de wijziging maakt hem ook echt doorvoert. De faalkost stopt met opbouwen, omdat de volgende collega nooit meer op de verouderde stap stuit. De volledige uitwerking staat in de zaak voor stapsgewijze handleidingen.
De kosten om de README te houden
De kosten om de README te houden worden niet betaald door zijn auteur. Ze worden betaald door de seniors die de DMs beantwoorden en door de nieuwe collega's wier eerste PR twee weken opschuift. Daarom blijft die kost onzichtbaar voor de engineer die het bestand zou kunnen herschrijven. De boekhouding klopt niet, en slechte boekhouding beschermt slechte patronen.
Reken het door bij vijfenzestig engineers, vier nieuwe collega's per kwartaal, drie weken inwerken. Elke nieuwe collega genereert ongeveer zes DMs in week één. Elke DM kost twintig minuten zodra je context-switching meerekent. Dat is twee uur senior-tijd per nieuwe collega, alleen al voor de voor de hand liggende fouten, vóór de echte hulp bij het opzetten. Vier nieuwe collega's per kwartaal aan twee uur per stuk, dat zijn acht uur per kwartaal aan vragen die een gids had kunnen opvangen.
De kost per nieuwe collega is scherper. Twee weken vastgelopen ramp betekent nul gemergde PRs in de eerste twee weken. Bij 200.000 $ aan volledig belaste kosten per senior per jaar (de conservatieve schatting voor een Series B observability-platform), kost twee weken nul output ongeveer 7.700 $ per nieuwe collega, omgerekend rond 7.100 €, wat het bedrijf slikt omdat de README rotte. Vermenigvuldig met vier nieuwe collega's per kwartaal en je zit op zo'n 123.000 $ op jaarbasis.
De kost stapelt zich op omdat hij in geen enkele OKR per kwartaal verschijnt. De kost van die documentatierot wordt door de engineering-organisatie als geheel betaald en duikt in niemands review op. De uitweg is om de kost te leggen bij wie hem kan voorkomen: wie de tool aanpast, herstelt de stap in dezelfde vijf minuten. Daar is het teamabonnement vanaf 12 $ per seat voor, en de berekening rechtvaardigt de uitgave bijna altijd al binnen het eerste kwartaal.
Er is ook een zachtere kost. Een nieuwe collega die in week één te veel leugens raakt, begint met de verkeerde kalibratie. Hij leert dat documentatie onbetrouwbaar is, dat antwoorden in DMs aan seniors zitten, dat processen rotten. Die kalibratie is moeilijk om te keren wanneer leadership later van diezelfde engineers verwacht dat ze zelf goede docs schrijven.
Wanneer een README nog wel het juiste formaat is
Een README blijft het juiste formaat voor wat zelden verandert en in z'n geheel wordt gelezen. Drie gevallen kwalificeren, de rest hoort thuis in opgenomen gidsen.
Eerste geval: de doelverklaring van het project. Wat het systeem doet, wat het niet doet, wie eigenaar is. Deze informatie verandert hoogstens één keer per jaar. Een lezer scant, begrijpt, gaat door. Een README-zin is de juiste vorm.
Tweede geval: de bijdragegids van een open-source-project. Codestijl, branchconventies, PR-format op GitHub, contributor license agreement. Deze regels gelden voor incidentele bijdragers die nooit in de Slack van het team zullen zitten. De lezer heeft geen toegang tot een Capture-workspace, geen senior om een DM te sturen, en heeft baat bij een autonome tekst die direct op GitHub te lezen is. De README is hier het juiste vehikel.
Derde geval: het architectuuroverzicht op hoog niveau, het globale schema en de beschrijving van wie met wie praat. Dit document verandert wanneer de architectuur verandert, ongeveer één à twee keer per jaar op een stabiel systeem. Het wordt gelezen om te begrijpen, niet om uit te voeren, en het patroon "één keer lezen" sluit aan bij het README-formaat.
Alles wat vaker dan eens per kwartaal verandert en wordt gelezen om uit te voeren, past niet. Setup van de dev-omgeving, deploy-flow, on-call-runbook, debug-patronen op Adyen-webhooks of Booking.com Engineering-services, de vier schaduw-dependencies die de auth-service blokkeren. Dat alles rot in het tempo van de onderliggende tools en heeft baat bij een opname per stap die in twee minuten ververst wordt.
Een tweede invalshoek op deze splitsing zit in hoe je de klant-onboarding-workflow documenteert, dat hetzelfde argument in een ander domein verdedigt. Het structurele defect is identiek: één bestand kan een proces dat sneller verandert dan het wordt gereviseerd niet bijhouden. De uitweg gaat van het ene domein naar het andere mee.
Veelgestelde vragen.
- Hoeveel tijd kost het om een README van 2.400 regels te vervangen door opgenomen gidsen?
Sjoerd, staff engineer bij het B2B observability-platform, heeft de hoofdgids van drieëntwintig stappen in ongeveer vier uur opgenomen, voice-over inbegrepen. Elk van de zes troubleshooting-gidsen kostte rond de dertig minuten. Het totaal blijft onder twee mensdagen, sneller dan de drie eerdere README-herschrijvingen die het team had geprobeerd. Cijfers in detail in het verhaal over engineering-team-documentatie.
- Wie onderhoudt de gidsen wanneer de oorspronkelijke auteur naar iets anders gaat?
Wie de tool aanpast, neemt de betreffende stap opnieuw op. De onderhoudskost is twee minuten per wijziging, laag genoeg dat engineers het echt doen in plaats van het door te schuiven. Het patroon werkt omdat de update wordt betaald door dezelfde persoon die de behoefte heeft veroorzaakt, wat de asymmetrie wegneemt die een README laat rotten. Een kwartaal-review vangt eventuele vergeten stappen af, maar de kost per stap is laag genoeg dat het kwartaal-ritme vooral een vangnet is.
- En engineers die liever tekst lezen dan een gids bekijken?
Capture-gidsen zijn geen video. Elke stap is een screenshot plus een geschreven beschrijving, exporteerbaar naar Markdown, HTML of PDF. Wie wil scannen, doet dat zoals bij een README, alleen kloppen de screenshots dit keer. De voice-over is optioneel en wordt gerenderd als tekst die uitgelijnd staat naast elke stap. Het format optimaliseert voor scan-lezers, wat het NNGroup-onderzoek over leesbaarheid en begrip aanwijst als de manier waarop technische documentatie in de praktijk wordt geconsumeerd.
- Werkt dit ook voor open-source-projecten met externe bijdragers?
Gedeeltelijk. Het architectuuroverzicht, de bijdragegids en de doelverklaring blijven in de README, omdat externe bijdragers geen toegang hebben tot een privé-workspace. De setup van de dev-omgeving kan als PDF of HTML worden geëxporteerd en in de repo worden gecommit, zodat externe bijdragers hetzelfde scan-vriendelijke format krijgen zonder dat maintainers een bestand van 2.400 regels hoeven te dragen. De splitsing is helder: statische inhoud in de README, uitvoerbare workflows in opgenomen gidsen.
- Vanaf welke teamgrootte wordt deze overstap rendabel?
De overstap begint zich rond vijftien engineers terug te verdienen, wanneer de DM-aan-seniors-belasting zichtbaar wordt. Daaronder wordt de README meestal onderhouden door dezelfde persoon die hem leest. Boven de vijftig engineers overstijgen de interruptiekosten van seniors wat het format kan absorberen. De staff engineer of engineering manager bij een B2B SaaS in de range van vijftig tot tweehonderd is de persona die het scherpste rendement haalt.
Klaar om je engineering-README te vervangen door twaalf opgenomen gidsen?
Capture neemt de setup eenmalig op een verse laptop op, narreert elke stap en exporteert een gids per stap die in twee minuten ververst wordt zodra een tool verandert. De tijd tot de eerste gemergde PR daalt in de bovenstaande case van drie weken naar één.
Stapsgewijze handleidingen: zes teams, één patroon
De senior collega die de workflow uit het hoofd kent, wordt het knelpunt. De wiki rot weg. De Loom die niemand bekijkt verzamelt stof in een map. Stapsgewijze handleidingen breken dat patroon in de zes teams die we het in productie hebben zien doen.
Hoe documenteer je een klant-onboarding-workflow in 2026
De meeste onboarding-documentatie is na acht weken verouderd, omdat niemand ze opnieuw opneemt wanneer de UI een update krijgt. De oplossing zijn geen betere schrijvers. Het is een recording-first methode die tien minuten per refresh kost.
De 12-stappen-regel: waarom lengte falen voorspelt
De meeste documentatie-teams schrijven langer dan ze zouden moeten. Lengte werkt tegen je, en 12 stappen is het operationele plafond waarboven de voltooiing instort.
Neem één workflow op.
Gratis Chrome-extensie. Geen registratie nodig.