My first day at a fintech startup in London, I was handed a laptop with Ubuntu pre-installed, pointed at a Confluence page titled “Getting Started (OUTDATED - see Dave)”, and told Dave was on holiday. The Confluence page referenced a Docker Compose setup that hadn’t worked since the previous quarter. By 4pm I’d cloned six repos, broken my local Postgres twice, and shipped exactly nothing.
I became CTO of that company. The fintech startup. And the first thing I fixed was onboarding.
Not because it was the sexiest problem. Because it was the most expensive one nobody was measuring.
The Real Cost Nobody Tracks
When I was building Decloud during my EF batch in 2019, every week a new engineer spent confused was a week we didn’t have. At a startup, a slow ramp-up isn’t an inconvenience. It’s an existential threat. But even at larger places, the math is brutal: a senior engineer who takes eight weeks to ship independently instead of three just cost you five weeks of salary for zero output. Multiply that by every hire per year.
The usual excuse is “our codebase is complex.” No. Your onboarding is lazy. Complexity is a reason to invest more in onboarding, not less.
What “Good” Actually Looks Like
I’ve onboarded engineers at the fintech startup, at Dropbyke in Seoul, and at Decloud. Different products, different stacks, different countries. The pattern that works is boringly consistent.
Day one: the new engineer opens a PR. Not a meaningful one. Not a feature. A typo fix, a config tweak, a test improvement. The point is they’ve touched the full cycle – clone, build, branch, change, test, review, merge, deploy – before they go home. If your setup takes longer than a morning, it’s broken.
Week one: they own a real bug fix. Something with a clear repro, a limited blast radius, and enough context that they learn the codebase by reading the code that matters, not by reading a stale architecture doc.
Month one: they’re independently picking up work. They know who to ask, where the bodies are buried, and how deploys actually work (not how the wiki says they work).
That’s it. No elaborate 90-day plans. No onboarding “program” with a PowerPoint deck. Just a tight loop of ship, learn, ship.
make setup Or Go Home
At Dropbyke, we ran Go services talking to a handful of microservices. When I joined (before eventually leading the engineering), the local dev setup involved seventeen manual steps spread across a README that contradicted itself in three places. I rewrote it as a Makefile.
git clone [email protected]:company/app.git
make setup
make dev
Three commands. If it takes more than three commands to go from zero to a running local environment, you have a setup problem, not a complexity problem. Script it, containerize the dependencies, seed the database automatically. The new hire’s laptop is a test of your infrastructure’s maturity. If you can’t reproduce your dev environment reliably, what makes you think production is any better?
When I set up the dev environment at Decloud, I literally timed it. Fifteen minutes from git clone to running tests. If it crept past that, we treated it as a bug.
The Buddy System (Done Right)
Every new engineer gets a buddy. Not their manager. Not the tech lead. Someone close enough to the codebase to answer “where does this thing live?” questions but not so senior that the new hire feels stupid asking.
The buddy’s job is simple: be interruptible for the first two weeks. That’s the whole job description. They don’t need to teach. They need to unblock.
At the fintech startup, I paired each new hire with whoever had last touched the area of code they’d be working in. Not because that person was the best teacher, but because they had the freshest context. Onboarding is a transfer of context, not knowledge. The knowledge is in the code. The context – why this weird pattern exists, which service is actually deprecated but still running, where the real config lives – that’s in people’s heads.
Starter Tasks That Aren’t Insulting
The worst onboarding pattern is the “starter project” that’s actually a garbage task nobody else wanted to do. New engineers can smell it. It tells them their time isn’t valued.
Good starter work has three properties:
- It touches production. The whole point is building confidence that they can ship safely.
- It has a clear definition of done. Not “explore the payment service and propose improvements.” That’s a research project disguised as onboarding.
- It teaches something specific about your system. A bug in the notification service teaches them about the event pipeline. An error message improvement teaches them about the API contract.
At Decloud, I kept a backlog of tagged issues specifically for this. Not fake work. Real bugs and improvements that were scoped to one or two days and came with enough context that someone new could pick them up without a forty-minute walkthrough.
Documentation: Less Is More
I’ve seen onboarding wikis with fifty pages of architecture history, org charts, and “philosophy” documents. Nobody reads them. The new hire skims the first two, gets overwhelmed, and asks their buddy anyway.
Here’s what new engineers actually need written down:
- How to set up their machine (the Makefile)
- How to deploy and how to roll back
- How to ask for help and who reviews what
- A one-page system overview with a data flow diagram
That’s four documents. Keep them short. Update them every time someone joins and finds something wrong. The onboarding docs should be the most maintained docs in your entire company, because they’re the only ones that get tested regularly by people who have no prior context.
The Feedback Loop Most Teams Skip
Here’s the thing that separates decent onboarding from great onboarding: you actually ask the new hire what was broken.
Every new engineer who joins should file at least one issue against the onboarding process itself. Not as a suggestion. As a requirement. “What was confusing? What was wrong? What did you have to ask someone that should have been written down?”
At the fintech startup, we turned this into a standing item in the 30-day check-in. Every single round of onboarding made the next one better. By the time I left, the setup was tight enough that contractors could be productive on day two.
Quick take
Stop treating onboarding as “show them the wiki and hope for the best.” Script the dev setup to three commands. Pair them with a buddy who has fresh context. Give them real work that touches production in week one. Then ask them what was broken and fix it. Repeat until your onboarding is your competitive advantage, not your embarrassment.