Remplacer un README de 2 400 lignes par douze guides.
Un staff engineer dans une plateforme d'observabilité B2B a enregistré le setup de l'environnement de dev une fois. Le time-to-first-PR des nouvelles recrues est passé de trois semaines à une.
01
Le doc d'onboarding ingé était un README de 2 400 lignes. Il était exhaustif et pas fiable. Certaines sections référençaient un build system qui avait été remplacé. Certaines supposaient une version d'OS qu'aucun laptop dans la boîte ne tournait plus. La phrase 'ça devrait juste marcher' apparaissait dix-sept fois.
Chaque nouvel ingé se prenait les mêmes échecs: extension Postgres manquante, mauvaise version de Node, le certificat SSL à régénérer, les quatre variables d'environnement que personne n'avait documentées. Chaque échec devenait un DM Slack à un senior. Au deuxième mois d'une vague de recrutement, les seniors passaient la moitié de leur semaine sur l'onboarding.
La solution que tout le monde proposait était 'réécrire le README'. Trois ingés avaient essayé l'année précédente. Chaque réécriture était bonne pendant deux semaines, puis devenait obsolète. Le README pourrissait parce que personne n'en était owner. Le coût se distribuait sur chaque senior qui répondait aux mêmes DM.
02
Le setup a été enregistré depuis zéro sur un laptop neuf, avec Capture qui tournait. Chaque étape et chaque échec ont été commentés. La sortie est un guide de vingt-trois étapes avec des screenshots du setup réel actuel.
Le guide a remplacé le README. Les nouvelles recrues l'ouvrent au jour 1 et le déroulent. Les six modes d'échec connus ont chacun leur propre guide de troubleshooting court, lié depuis le principal.
Quand une étape change (mise à jour d'un outil, nouvelle variable d'env), l'étape concernée est réenregistrée. Deux minutes de travail, pas une réécriture de README. Les DM d'onboarding adressés aux seniors sont passés de six par nouvelle recrue en première semaine à un environ. Et celui qui reste touche un cas réellement intéressant.
03
- 01Faire le setup en direct.
Laptop neuf, Capture qui tourne. Commenter chaque étape, y compris les échecs.
- 02Traiter les échecs comme des citoyens de premier rang.
Chaque mode d'échec connu a son propre guide de troubleshooting court.
- 03Lié depuis un seul endroit.
Le wiki engineering a une seule entrée: Commencez ici.
- 04Maintenir étape par étape.
Réenregistrer l'étape concernée quand un outil change. Pas le guide entier.
- 05Mesurer le temps jusqu'à la première PR.
Le succès de l'onboarding se mesure au temps jusqu'à la première PR mergée.
04
Le time-to-first-PR est passé de trois semaines à une. Les seniors ont récupéré leur semaine 1. Le volume de DM liés à l'onboarding a baissé d'environ 80%.
Le pattern s'est diffusé. Le runbook d'astreinte a eu le même traitement. Le processus de revue de PR a été enregistré. Le flow de déploiement a été enregistré. Le wiki engineering tient maintenant en douze guides, pas en 2 400 lignes de README à moitié obsolète.
Enregistrez un workflow.
Extension Chrome gratuite. Sans inscription.
Customer Success a rangé le Zoom d'onboarding.
Les appels de 45 minutes sont devenus des guides de 12 minutes. Le portefeuille a grandi de 80% sans recruter.
Les Ops ont reconstruit la bibliothèque de SOP avant l'audit.
Vingt et un processus, enregistrés par leurs owners. SOC 2 clos deux semaines en avance.
L'IT a réduit les tickets Tier 1 d'un tiers.
Vingt questions récurrentes, vingt guides, huit semaines. Les lundis ont récupéré leurs après-midi.