Onboarding degli ingegneri più veloce (senza docs migliori)
Onboarding degli ingegneri più veloce: il vero ostacolo è il contesto disperso su Slack, GitHub e Linear che nessun wiki riesce a catturare.
By Ellis Keane · 2026-03-31
Quando mi sono unito a un team che non sapeva come lavorava
Se vi state chiedendo come fare onboarding degli ingegneri più veloce, lasciatemi raccontare della mia esperienza di onboarding – perché è probabilmente il mio argomento migliore.
Nel 2019 mi sono unito a una startup a San Francisco come loro terzo ingegnere. Il CTO – un tipo brillante e spettacolarmente disorganizzato – mi ha consegnato un laptop il primo giorno dicendo sostanzialmente: «Il codebase è su GitHub. Usiamo Slack per tutto il resto. Buona fortuna.»
Quello era il programma di onboarding.
Ho trascorso le prime tre settimane a fare qualcosa che, in retrospettiva, non aveva nulla a che fare con l'ingegneria: archeologia. Scavando nei thread Slack di sei mesi prima per capire perché il sistema di autenticazione era stato costruito in quel modo. Scorrendo PR GitHub chiuse per trovare conversazioni sulle decisioni dello schema del database che nessuno aveva documentato da nessuna parte (ovviamente). Facendo domande in #general che ricevevano risposta «ah sì, quello – abbiamo cambiato idea in gennaio, guarda il thread con il nostro designer.»
Quale thread? Con quale designer? In quale canale?
Non era un cattivo manager. Operava in un mondo dove la conoscenza istituzionale viveva esclusivamente nelle teste delle persone e dispersa su quattro strumenti diversi – il che, se siamo onesti, descrive la maggior parte dei team di engineering. Ogni domanda che facevo richiedeva a qualcuno di fermare quello che stava facendo, fare un cambio di contesto in «modalità onboarding», scavare il thread o documento pertinente, e poi cercare di ricostruire il ragionamento dietro una decisione presa mesi prima. Si sentivano quasi gli ingranaggi mentali cigolare.
Tre settimane di un ingegnere che fa archeologia invece di engineering, più il costo cumulativo delle interruzioni di tutti coloro che rispondevano alle mie domande – sono soldi veri, anche se non appaiono mai in un bilancio.
Quella esperienza non era nemmeno unica. Ho trascorso un decennio a gestire Vulcan, la nostra agenzia di design e engineering, e una parte sorprendente di quel tempo a entrare in organizzazioni ancora più disorganizzate di me (un basso standard, onestamente). Ogni cliente, stesso schema: la conoscenza esisteva, viveva semplicemente nelle teste delle persone e in strumenti che nessuno aveva pensato di connettere.
Come fare onboarding degli ingegneri più veloce: risolvi il problema della ricerca, non della documentazione
La maggior parte dei manuali di onboarding trattano l'onboarding degli ingegneri come un problema di contenuto. Scrivi docs migliori! Crea un wiki su Notion! Crea una checklist di onboarding con traguardi codificati per colore!
Le checklist vanno bene. Non vi dirò di buttare il vostro template «Giorno 1 – Giorno 30». Ma il vero collo di bottiglia non è «non abbiamo abbastanza documentazione». È che il contesto utile – le cose disordinate, sfumate, reali – vive in thread Slack, commenti a PR GitHub, descrizioni di issue Linear e nell'occasionale annotazione Figma che un designer ha lasciato sei settimane prima dell'arrivo del nuovo assunto. Abbiamo collettivamente trascorso due decenni a costruire wiki che descrivono cosa fa il software, e quasi nessun tempo a rendere il perché scopribile.
Nessun wiki cattura il «perché». I wiki catturano ciò che qualcuno ha ritenuto valesse la pena scrivere – il che è una cosa completamente diversa da ciò che un nuovo ingegnere ha davvero bisogno di sapere.
Il vero collo di bottiglia dell'onboarding non è la documentazione – è che il contesto utile vive in strumenti che nessuno ha pensato di cercare. attribution: Chris Calo
Da quando onboardo ingegneri – prima in un'agenzia di design, poi costruendo Sugarbug – ho osservato lo stesso schema ripetersi. Le domande che fanno i nuovi assunti rientrano in circa quattro categorie, e solo una di esse è affrontata dalla documentazione di onboarding tradizionale:
Cosa coprono i docs
- Panoramica dell'architettura – diagrammi di sistema, confini dei servizi, topologia di deployment
- Setup locale – come clonare, costruire, eseguire e testare
- Standard di codice – regole di linting, convenzioni delle PR, pattern di denominazione
Cosa mancano i docs
- Storico delle decisioni – perché questa architettura e non le tre alternative discusse su Slack?
- Conoscenza tribale – chi è davvero responsabile del modulo di fatturazione? chi ha preso quella decisione CSS?
- Catene di contesto – un issue Linear collegato a una PR collegata a una discussione di design collegata a una spec di prodotto
- Stato attivo – su cosa si sta lavorando adesso, e perché?
La colonna «Cosa coprono i docs» è quella per cui la maggior parte dei team ottimizza. Dalla mia esperienza, la colonna «Cosa mancano i docs» è dove i nuovi ingegneri trascorrono la maggior parte del loro tempo di ramp-up – è lì che vivono le risposte vere, ed è lì che nessuno pensa di indirizzare i nuovi assunti.
Quelle informazioni non mancano perché nessuno le ha scritte. Sono state scritte – in un messaggio Slack, un commento di review GitHub, un aggiornamento di issue Linear. Il problema è la reperibilità, non la documentazione.
La tassa di interruzioni che nessuno mette in bilancio
Ogni volta che un nuovo ingegnere chiede «perché l'abbiamo costruito così?» e un ingegnere senior smette quello che sta facendo per rispondere, accadono due cose. Il nuovo assunto ottiene una risposta (bene), e l'ingegnere senior perde un pezzo significativo di concentrazione produttiva – non i 2 minuti che ha richiesto la domanda, ma i circa 15 minuti necessari per trovare il thread pertinente, ricordare il ragionamento e rifocalizzarsi su quello che stava facendo prima.
stat: "Diverse al giorno" headline: "Interruzioni causate da un singolo ingegnere in fase di adattamento" source: "Basato sui nostri schemi di onboarding in Sugarbug"
Quando si assumono due ingegneri nello stesso trimestre (il che, se sei una startup in crescita, probabilmente fai), il tuo team esistente assorbe un numero genuinamente irragionevole di interruzioni per settimane. Le persone che hai assunto per aumentare la velocità la stanno temporaneamente diminuendo. Nessuno la mette in bilancio perché nessuno la misura – si manifesta solo come vaga sensazione che «il team sembra più lento questo trimestre» senza che nessuno la colleghi all'onboarding.
E la parte che brucia di più: le risposte a queste domande esistono già da qualche parte. Sono in Slack, in GitHub, in Linear. Le informazioni sono state catturate nel momento in cui la decisione è stata presa. Sono solo in uno strumento che nessuno ha detto al nuovo assunto di cercare, in un canale che non sa che esiste, sotto un titolo di thread che non ha senso fuori contesto.
Contesto connesso: cosa significa in pratica
Il contesto connesso nell'onboarding degli ingegneri significa che un nuovo assunto può cercare in tutti gli strumenti che il vostro team utilizza – Slack, GitHub, Linear, Notion – da un'unica interfaccia. Non solo ricerca per parole chiave (la ricerca di Slack è, diciamolo, adeguata nel migliore dei casi e attivamente ostile nel peggiore), ma ricerca contestuale che comprende le relazioni tra le cose.
«Mostrami tutto ciò che riguarda il refactoring del modulo di fatturazione» restituisce: l'epic Linear, le sei PR su GitHub, il thread Slack dove il team ha dibattuto l'approccio, e il documento di architettura Notion – tutto collegato, tutto in ordine cronologico, senza archeologia.
Questo è il concetto: un grafo della conoscenza che mappa le relazioni tra il lavoro del vostro team in tutti gli strumenti, creando un indice dinamico di chi ha deciso cosa, dove e perché.
Ben e io abbiamo costruito questo perché avevamo trascorso anni a vivere l'alternativa. A Vulcan, gestivamo team di design e engineering in diverse organizzazioni contemporaneamente, e invariabilmente le nostre vere specialità si riducevano a una cosa sola: router umani glorificati di informazioni. Due persone che avrebbero dovuto progettare e costruire trascorrevano invece le giornate a rispondere «dov'è quella cosa?» (una realizzazione desolante, fidatevi). Doveva smettere.
Il contesto connesso non riguarda la scrittura di altra documentazione – si tratta di rendere il contesto che già esiste nei vostri strumenti scopribile, ricercabile e collegato. I nuovi ingegneri non dovrebbero dover sapere in quale canale Slack cercare o quale repository GitHub controllare.
Questo è ciò che stiamo costruendo con Sugarbug. Il grafo della conoscenza collega gli issue Linear alle PR GitHub, alle conversazioni Slack, ai documenti Notion, e rende tutto ricercabile. Quando si unisce un nuovo assunto, ha a disposizione la storia delle decisioni del team dal primo giorno. (Stiamo ancora perfezionando i flussi di lavoro specifici per l'onboarding, onestamente – ma il grafo sottostante è la base.)
Un framework di onboarding degli ingegneri in 3 settimane
Ecco il framework che avrei voluto avere quando mi fu consegnato quel laptop con il «buona fortuna». Se stai cercando di capire come fare onboarding degli ingegneri più veloce, questo funziona perché affronta il vero collo di bottiglia (la reperibilità) piuttosto che quello immaginario (il volume della documentazione).
Settimana 1: Orientarsi
Affianca al nuovo assunto una «guida al contesto» – non un mentor, ma qualcuno che sa bene dove vivono le informazioni (non necessariamente la persona più senior – a volte è la persona che ha fatto più domande di recente e ha la mappa più aggiornata di dove si trovano le cose). Il lavoro della guida al contesto non è rispondere a ogni domanda. Il suo lavoro è dire: «Quella decisione è stata presa nel canale #backend intorno a febbraio, lasciami aiutarti a trovare il thread.»
Se stai usando uno strumento di contesto connesso come Sugarbug, il lavoro della guida al contesto diventa considerevolmente più semplice: «cerca "refactoring modulo fatturazione" e vedrai la catena di decisione completa.»
Settimana 2: Navigare
Il nuovo assunto dovrebbe ora fare le sue prime PR, ma soprattutto dovrebbe costruire il suo modello mentale di come il team comunica. Quali discussioni avvengono su Slack? Quali nei commenti di Linear? Quali nelle review delle PR GitHub? Capire la topologia della comunicazione è importante quanto capire il codebase – forse di più, nel primo mese. (Ho visto ingegneri che hanno capito il codebase in una settimana ma ancora non sapevano dove trovare le decisioni tre settimane dopo.)
Settimana 3: Contribuire
Alla terza settimana, se il problema del contesto è risolto, un nuovo ingegnere dovrebbe dare contributi significativi – non perché abbia memorizzato il codebase, ma perché sa come trovare quello che gli serve senza interrompere nessuno.
- [x] Giorno 1: Ambiente locale funzionante, accesso a tutti gli strumenti concesso
- [x] Giorno 2–3: Guida al contesto assegnata, presentazione della topologia di comunicazione
- [x] Settimana 1: 2–3 «buoni primi issue» completati con il supporto della guida al contesto
- [ ] Settimana 2: Creazione di PR indipendenti, ricerca di contesto prima di chiedere
- [ ] Settimana 3: Contributo alle discussioni di design, revisione delle PR degli altri
- [ ] Mese 2: Produttivo in autonomia, check-in settimanali con la guida al contesto
Perché questo si moltiplica (e i wiki no)
La differenza tra risolvere l'onboarding degli ingegneri con il contesto connesso e risolverlo con un wiki Notion di 47 pagine che nessuno mantiene (sapete quale – aggiornato l'ultima volta otto mesi fa da qualcuno che nel frattempo se n'è andato) è che il contesto connesso si moltiplica. Ogni conversazione del vostro team su Slack, ogni review di PR, ogni aggiornamento di issue Linear – tutto viene indicizzato, collegato e reso ricercabile. Il grafo della conoscenza diventa più ricco nel tempo senza che nessuno faccia lavoro extra.
La seconda assunzione beneficia di tutto ciò che le domande di onboarding della prima hanno scoperto. La quinta assunzione ha un grafo ancora più ricco. Alla decima, la conoscenza istituzionale che in precedenza viveva esclusivamente nella testa del vostro CTO è distribuita, ricercabile e connessa.
E questa è la parte che mi entusiasma davvero di questo approccio! Non solo il guadagno di efficienza – sebbene dalle nostre prime conversazioni con team che provano il contesto connesso, la compressione del tempo di ramp-up sia reale. E questa è la parte che non mi aspettavo: Ben e io siamo molto loquaci, e metà delle nostre idee migliori svanisce nel rumore quotidiano prima che uno di noi le scriva (molto professionale, lo so). Il grafo continua a far emergere scorciatoie e intuizioni genuinamente utili dalle nostre conversazioni che avevamo completamente dimenticato. Se riesce a salvare il contesto delle due persone che lo hanno costruito, immaginate cosa fa per un nuovo assunto che entra in un team di quindici persone.
Il valore più profondo, per i team che cercano davvero di fare onboarding degli ingegneri più veloce, è che si smette di perdere la conoscenza istituzionale quando le persone se ne vanno. La catena di contesto delle loro decisioni rimane, ricercabile, per tutti coloro che vengono dopo. Non è un guadagno di efficienza. È una memoria organizzativa.
Ricevi l'intelligence dei segnali direttamente nella tua casella di posta.
Domande frequenti
Q: Quanto tempo dovrebbe richiedere l'onboarding di un nuovo ingegnere? A: Dalla nostra esperienza e dalle conversazioni con altri team di engineering, 2–3 mesi è il tempo tipico prima che un nuovo ingegnere sia pienamente produttivo. Il collo di bottiglia è raramente la competenza tecnica – è imparare dove risiedono le decisioni, chi è responsabile di cosa e come il team comunica davvero tra gli strumenti. I team che usano strumenti di contesto connesso segnalano una riduzione significativa di questo tempo, sebbene il miglioramento esatto dipenda dalla dimensione del team e dalla complessità degli strumenti.
Q: Sugarbug aiuta con l'onboarding degli ingegneri? A: Sì. Sugarbug costruisce un grafo della conoscenza dinamico attraverso i tuoi account Linear, GitHub, Slack e Notion, così i nuovi ingegneri possono cercare in ogni strumento le decisioni passate, il contesto sul perché le funzionalità sono state costruite e chi contattare per cosa – senza interrompere nessuno.
Q: Cos'è il contesto connesso nell'onboarding degli ingegneri? A: Il contesto connesso significa collegare le informazioni tra gli strumenti in modo che un nuovo assunto possa tracciare una decisione dall'issue Linear attraverso la PR GitHub fino al thread Slack dove il team ha dibattuto l'approccio. Quando quella catena è ricercabile, il tempo di ramp-up diminuisce perché il nuovo assunto può trovare risposte autonomamente senza interrompere i colleghi.
Q: Perché i wiki di onboarding tradizionali non funzionano per gli ingegneri? A: I wiki catturano ciò che qualcuno ha ritenuto valesse la pena scrivere – panoramiche dell'architettura, guide di configurazione, standard di codice. Il vero collo di bottiglia del ramp-up è il materiale disordinato e contestuale che vive nei thread Slack, nei commenti alle PR e negli issue Linear. Perché è stato costruito così? Chi ha preso quella decisione? Quel contesto è già catturato nei vostri strumenti – il problema è trovarlo, non scriverlo.
Q: Sugarbug si integra con GitHub e Linear per l'onboarding? A: Sì. Sugarbug si connette a GitHub, Linear, Slack, Notion, Figma e Google Calendar tramite API, indicizzando conversazioni, issue, PR e documenti in un grafo della conoscenza ricercabile che i nuovi ingegneri possono interrogare dal primo giorno.