Pourquoi l'onboarding engineer via README pourrit toujours
Tout README d'onboarding pourrit en deux trimestres. Le défaut est structurel, pas éditorial, et le réécrire plus fort ne corrige rien.
- Délai première PR mergée
- 1 semaine
- DM Slack en semaine 1
- 1
- "Ça devrait marcher"
- 17 fois
- Setup terminé sans aide
- 90 %
L'essentiel.
Un README est un document unique qui prétend être la trace canonique de chaque étape utile à un nouvel ingénieur pour démarrer. Le motif d'échec est précis : il pourrit en deux trimestres, et la pourriture n'est pas un problème de rédaction. C'est un problème de structure, parce qu'un seul fichier doit suivre un système qui change tous les jours, entre versions de Postgres, versions de Node, certificats SSL, tunnels VPN, variables d'environnement et les quatre scripts dans `bin/` que personne ne possède. Réécrire le README plus fort offre deux semaines propres puis la même pourriture revient. La sortie consiste à arrêter de traiter l'onboarding comme un document.
Les 17 endroits où le README ment
Un README ne ment pas par malveillance. Il ment parce que chaque affirmation a une demi-vie plus courte que la cadence de relecture du fichier. La phrase "ça devrait marcher" apparaît dix-sept fois dans le README de 2 400 lignes que Marc, staff engineer dans une plateforme d'observabilité B2B, a remplacé le trimestre dernier. Chaque occurrence marquait un endroit où l'auteur avait épuisé sa patience sur un cas limite.
Le catalogue ci-dessous vient du diff d'un vrai README d'onboarding, série B, équipe de soixante-cinq ingénieurs.
| Type de mensonge | Phrase typique | Réalité | |
|---|---|---|---|
| 1 | Dérive de version | "Installer Node 18" | Node 20.6 minimum, 18 plante sur un decorator TypeScript |
| 2 | Outil remplacé | "Lancer make build" | Makefile supprimé au T2, remplacé par un script Bun |
| 3 | Silence sur la config | "Ajouter les variables d'env" | Quatre vars non documentées bloquent le serveur dev |
| 4 | Capture d'écran périmée | Vieux screenshot console AWS | Console refondue, le bouton est dans un autre menu |
| 5 | Hypothèse OS | "Brew install Postgres" | Sur Linux il faut apt, aucun chemin alternatif |
| 6 | Hypothèse réseau | "Le VPN devrait se connecter" | Le firewall corp bloque l'échange de cert sur macOS Sonoma |
| 7 | Ordre faux | Étapes 4 et 5 inversées | L'ordre listé corrompt la base locale |
| 8 | Trou de permission | "Vous devriez avoir accès" | Les recrues récupèrent l'accès au jour 3, pas au jour 1 |
| 9 | Branche par défaut | "Checkout main" | La branche par défaut est passée à trunk il y a six mois |
| 10 | Chemin de secrets | "Récupérer dans le vault" | Le chemin a changé, la commande CLI exige un flag |
| 11 | Demi-étape | "Lancer les migrations" | Le script de migration veut un flag absent du README |
| 12 | Dépendance fantôme | Pas de mention de Redis | Sans Redis, le service auth crash en silence |
| 13 | "Devrait" non vérifié | "Ça devrait marcher" | Non, l'échec est silencieux et les logs Sentry sont vides |
| 14 | Changement vendor | "Clés test Stripe" | La sandbox Stripe est remplacée par un mock interne |
| 15 | Script bin/ | "Lancer bin/setup" | Le script n'a pas bougé depuis 2023 et présume Python 2 |
| 16 | Renvoi cassé | "Voir le guide de déploiement" | Le guide a été supprimé lors d'un nettoyage Confluence |
| 17 | Session navigateur | "Login sur localhost" | Le cert auto-signé est bloqué par Chrome sans override manuel |
make build"main"trunk il y a six moisbin/setup"Chaque mensonge est petit. La somme transforme la première semaine d'une recrue en chantier d'archéologie. La story de documentation engineering par guides sur la même plateforme l'a chiffré : chaque nouvelle recrue tombait sur six de ces échecs en semaine 1.
Pourquoi la réécriture du README ne tient jamais
Trois ingénieurs avaient tenté de réécrire le README dans l'année qui a précédé le travail de Marc. Chaque réécriture était excellente pendant deux semaines. Puis elle pourrissait. Le motif n'a rien à voir avec la discipline ou le talent rédactionnel. Il est structurel, et on peut prédire l'échec sans connaître l'équipe.
Un README a un seul auteur à un instant donné. La première réécriture survient quand le coût de la pourriture devient visible (une semaine de DM aux seniors par recrue). Quelqu'un se porte volontaire, bloque deux jours, sort un fichier solide. Il le merge. La semaine suivante, un outil monte de version, un script change, une variable d'env est ajoutée. L'auteur initial est passé à autre chose. Le changement n'est pas répercuté parce que le coût d'éditer le fichier dépasse celui d'écrire la réponse en DM Slack à celui qui demande. La pourriture redémarre en semaine 3.
Comparez avec la façon dont le code reste à jour. Le code ne pourrit pas au même rythme parce que le build casse quand le code dérive. Le README est un artefact en lecture seule du point de vue du build. Rien ne casse quand il décroche. La recherche NNGroup sur la lecture en F sur le web décrit le motif dominant : on scanne, on ne lit pas, et on accorde de moins en moins de crédit à un document à chaque affirmation fausse. Au troisième mensonge, la recrue ferme le fichier et ouvre un DM. Le senior répond, parce que répondre est plus rapide que réécrire la ligne 1 847.
La conclusion structurelle est nette. Un README est le mauvais format parce que le coût de maintenance est porté par une personne et le coût d'échec par une autre, et cette asymétrie rend la pourriture inévitable. La réécriture ne change pas l'asymétrie. Elle achète deux semaines et remet le compteur à zéro.
Le chemin qui marche aligne le mainteneur sur celui qui change l'outil : qui modifie un script réenregistre l'étape concernée en deux minutes, sans sprint de doc. C'est ce que pose le flux d'enregistrement de l'extension Chrome.
Ce qui remplace un README
Ce qui remplace un README, c'est douze guides courts, un par mode d'échec, enregistrés par l'ingénieur qui a résolu cet échec en dernier. Le README de 2 400 lignes de la plateforme d'observabilité a été remplacé par douze guides. Les chiffres se lisent directement : le délai de première PR est passé de trois semaines à une. Les DM Slack en semaine 1 vers les seniors sont tombés de six à un par recrue. Le setup terminé sans aide est passé de "presque jamais" à quatre-vingt-dix pour cent. Ces métriques permettent à un staff engineer ou un engineering manager de SaaS B2B, 50 à 200 ingénieurs, de défendre la bascule auprès du leadership.
La structure est précise. Un guide principal, vingt-trois étapes, déroule le happy path sur un laptop neuf. Chaque mode d'échec connu (mauvaise version de Node, certificat SSL, vars d'env manquantes, tunnel VPN, extension Postgres, les quatre scripts bin/) a son propre guide de troubleshooting court. Le guide principal pointe vers le guide de troubleshooting à l'étape exacte où l'échec apparaît typiquement. La recrue ne scanne plus 2 400 lignes pour trouver son erreur. Elle clique.
La forme de chaque guide compte. Les étapes sont numérotées. Chacune porte une capture de l'écran réel actuel, pas une approximation d'il y a un an. Chacune a la commande exacte, pas une paraphrase. La narration explique pourquoi l'étape existe, pas seulement ce qu'elle fait, parce qu'une recrue arrête de croire un document qui se lit comme un dump de commandes. La recherche NNGroup sur pourquoi les utilisateurs scannent au lieu de lire explique pourquoi ce format tient : on lit les premiers mots de chaque ligne, on regarde la capture, on avance. La granularité par étape colle au scan.
Quand un outil change, seule l'étape concernée est réenregistrée. Deux minutes, pas une refonte de README. Le coût de maintenance reste assez bas pour que l'ingénieur qui a fait le changement le porte vraiment. Le coût d'échec arrête de composer parce que la prochaine recrue ne tombe jamais sur l'étape périmée. Le déroulé complet vit dans pourquoi adopter les guides pas à pas.
Le coût de garder le README
Le coût de garder le README n'est pas payé par son auteur. Il est payé par les seniors qui répondent aux DM, et par les recrues dont la première PR glisse de quinze jours. C'est ce qui rend ce coût invisible pour celui qui pourrait réécrire le fichier. La comptabilité est fausse, et une mauvaise comptabilité protège les mauvais patterns.
Faites le calcul à soixante-cinq ingénieurs, quatre recrues par trimestre, trois semaines de ramp. Chaque recrue génère environ six DM en semaine 1. Chaque DM coûte vingt minutes une fois le context-switching compté. Soit deux heures de senior par recrue rien que sur les pannes évidentes, avant l'aide réelle au setup. Quatre recrues par trimestre à deux heures pièce, ça fait huit heures par trimestre de questions qu'un guide aurait absorbées.
Le coût par recrue est plus net. Deux semaines de ramp bloqué, c'est zéro PR mergée pendant la première quinzaine. À 200 000 $ de coût chargé par senior et par an (le chiffre conservateur pour une plateforme d'observabilité série B), deux semaines à zéro output coûtent environ 7 700 $ par recrue, soit autour de 7 100 €, que la boîte avale parce que le README a pourri. Multipliez par quatre recrues par trimestre et l'addition annuelle frôle 123 000 $.
Le coût s'accumule parce qu'il n'apparaît dans aucun OKR trimestriel. Le coût de pourriture est payé par l'organisation engineering globalement et ne ressort dans la review de personne. La sortie consiste à mettre le coût sur celui qui peut l'éviter : qui change l'outil, corrige l'étape, dans les mêmes cinq minutes. C'est ce que couvre le plan équipe à partir de 12 $ par siège, et le calcul justifie quasi systématiquement la dépense dès le premier trimestre.
Il existe un coût plus diffus. Une recrue qui ramasse trop de mensonges en semaine 1 démarre son poste avec le mauvais calibrage. Elle apprend que la doc est peu fiable, qu'on obtient des réponses en DM aux seniors, que les process pourrissent. Ce calibrage est dur à inverser quand le leadership demande plus tard à ces mêmes ingénieurs d'écrire de la bonne doc.
Quand un README reste le bon format
Un README reste le bon format pour ce qui change rarement et se lit en entier. Trois cas qualifient, le reste appartient aux guides enregistrés.
Premier cas : la déclaration de mission du projet. Ce que le système fait, ce qu'il ne fait pas, qui en est propriétaire. Cette information bouge une fois par an au plus. La lectrice scanne, comprend, passe. Une phrase de README est la bonne forme.
Deuxième cas : le guide de contribution d'un projet open source. Style de code, convention de branche, format de PR sur GitHub, contributor license agreement. Ces règles s'appliquent à des contributeurs ponctuels qui ne seront jamais dans le Slack de l'équipe. La lectrice n'a pas accès à un workspace Capture, n'a pas de senior à DM, et a besoin d'un texte autonome lisible directement sur GitHub. Le README est le bon véhicule ici.
Troisième cas : la vue d'architecture de haut niveau, le schéma global et la description de qui parle à qui. Ce document change quand l'architecture change, soit une à deux fois par an sur un système stable. Il se lit pour comprendre, pas pour exécuter, et le pattern lecture-une-fois colle au format README.
Tout ce qui change plus d'une fois par trimestre et se lit pour exécuter ne tient pas. Setup de l'environnement dev, flux de déploiement, runbook d'astreinte, patterns de debug Datadog ou Grafana, les quatre dépendances fantômes qui bloquent le service auth. Tout ça pourrit à la vitesse des outils sous-jacents et bénéficie d'un enregistrement par étape qui se rafraîchit en deux minutes.
Une seconde lecture sur ce partage vit dans comment documenter le parcours d'onboarding client, qui défend le même argument dans un autre domaine. Le défaut structurel est identique : un fichier unique ne peut pas suivre un process qui change plus vite qu'on ne le révise. La sortie passe d'un domaine à l'autre.
Questions fréquentes.
- Combien de temps pour remplacer un README de 2 400 lignes par des guides enregistrés ?
Marc, staff engineer chez la plateforme d'observabilité B2B, a enregistré le guide principal de vingt-trois étapes en environ quatre heures, narration comprise. Chacun des six guides de troubleshooting a pris autour de trente minutes. Le total tient sous deux jours-homme, plus rapide que les trois réécritures de README que l'équipe avait tentées avant. Détails chiffrés dans la story documentation engineering par guides.
- Qui maintient les guides quand l'auteur original passe à autre chose ?
Celui qui change l'outil réenregistre l'étape concernée. Le coût de maintenance est de deux minutes par changement, assez bas pour que les ingénieurs le portent vraiment au lieu de le repousser. Le pattern tient parce que le coût de la mise à jour est payé par la même personne qui a déclenché le besoin, ce qui supprime l'asymétrie qui fait pourrir un README. Une revue trimestrielle attrape les étapes qu'on aurait oublié de réenregistrer, mais le coût par étape est assez faible pour que le trimestriel reste un filet de sécurité.
- Et les ingénieurs qui préfèrent lire du texte plutôt que regarder un guide ?
Les guides Capture ne sont pas des vidéos. Chaque étape est une capture d'écran plus une description écrite, exportable en Markdown, HTML ou PDF. Une lectrice qui veut survoler le fait de la même manière qu'un README, sauf que les captures sont à jour. La narration est optionnelle et se rend en texte aligné sur chaque étape. Le format optimise pour le scan-reader, ce que la recherche NNGroup sur lisibilité, légibilité et compréhension montre comme la façon réelle dont la doc technique est consommée.
- Est-ce que ça marche pour un projet open source avec des contributeurs externes ?
Partiellement. La vue d'architecture, le guide de contribution, la déclaration de mission restent dans le README parce que les contributeurs externes n'ont pas accès à un workspace privé. Le setup environnement dev peut être exporté en PDF ou HTML et committé dans le repo, ce qui donne aux contributeurs externes le même format scannable sans forcer les mainteneurs à porter un fichier de 2 400 lignes. Le partage tient en deux : statique dans le README, exécutable dans des guides enregistrés.
- À partir de quelle taille d'équipe la bascule devient rentable ?
La bascule commence à payer autour de quinze ingénieurs, quand la taxe DM-aux-seniors devient visible. En dessous, le README est en général maintenu par celui ou celle qui le lit. Au-delà de cinquante ingénieurs, le coût d'interruption des seniors dépasse ce que le format absorbe. Le staff engineer ou l'engineering manager d'un SaaS B2B dans la fourchette 50 à 200 est le persona qui en tire le rendement le plus net.
Prêt à remplacer votre README engineering par douze guides enregistrés ?
Capture enregistre le setup une fois sur un laptop neuf, narre chaque étape et exporte un guide par étape qui se rafraîchit en deux minutes quand un outil change. Le délai de première PR mergée passe de trois semaines à une dans le cas étudié.
Votre agent IA ne peut pas automatiser un workflow qu'il n'a jamais vu
La connaissance des workflows reposait sur trois personnes seniors. En 2026, ce goulot devient un problème d'automatisation : les agents IA ne lisent pas les têtes, ils lisent des traces.
Guides pas à pas : six équipes, une seule mécanique
La personne senior qui connaît le workflow par cœur devient le goulot d'étranglement. Le wiki pourrit. La Loom que personne ne regarde s'empile dans un dossier. Les guides pas à pas cassent ce schéma dans les six équipes que nous avons vues le faire en production.
La règle des 12 étapes : pourquoi la longueur prédit l'échec
La plupart des équipes documentent plus long qu'elles ne devraient. La longueur joue contre vous, et 12 étapes est le plafond opérationnel au-delà duquel le taux de complétion s'effondre.
Enregistrez un workflow.
Extension Chrome gratuite. Sans inscription.