The usual failure mode for onboarding on a small team isn’t a bad plan – it’s no plan. Someone hands the new hire a laptop, adds them to Slack, and says “ping me if you get stuck,” which quietly means the new person spends their first three days reverse-engineering tribal knowledge that lives in nobody’s head but everyone’s memory. A week of deliberate onboarding gets someone shipping real code faster than a month of osmosis.
Day one: a working environment, nothing else
The only goal for day one is a running local environment and a merged pull request, even a trivial one – a typo fix, a small copy change, anything that goes through your real CI and deploy pipeline. This proves the setup works end to end and gives the new hire a concrete, low-stakes win on day one instead of a week of “still configuring my machine.”
If getting a new machine running takes more than an hour, that’s worth fixing independent of onboarding – it’s costing every new hire the same tax, and it’s usually a sign your setup relies on undocumented steps. The Joel Test’s line about building in one step is two decades old and still the right bar: someone new should be able to check out the repo and be running with a handful of commands, not a wiki page of manual steps (joelonsoftware.com – the joel test).
Days two and three: a real ticket, closely watched
Pick a small, well-scoped, genuinely useful ticket – not a “starter task” everyone knows is throwaway, and not something ambiguous enough to need three days of requirements clarification. Pair on it for the first hour, then let them drive with you one Slack message away. The point isn’t the ticket itself, it’s forcing contact with the actual codebase, the actual review process, and the actual deploy path while someone’s available to unblock quickly.
# A reasonable first-week ticket looks like:
- Touches 1-2 files, not the whole codebase
- Has a clear, testable definition of done
- Doesn't require design decisions or cross-team coordination
- Would take an experienced engineer under half a dayWrite the map down before they need it
A short doc that answers “where does X live” for the five or six things people ask about most – how the data model is organized, where background jobs run, how deploys work, who owns what – saves hours of interruption per new hire, and it only has to be written once. If you don’t have this, the new hire’s onboarding week becomes a series of interruptions for whoever’s closest, which is a cost you’re still paying every time someone joins.
Assign a specific person, not “the team”
“Ask anyone if you have questions” means asking no one, because nobody wants to be the person constantly interrupting five different people. Assign one buddy for the first two weeks whose explicit job includes answering questions, even ones that feel too basic to ask. Rotate who does this across hires so it doesn’t become one person’s permanent burden. A lightweight CODEOWNERS file also helps here, since it routes the new hire’s early PRs to the right reviewer automatically instead of them guessing who owns what.
Resist the urge to front-load documentation
Dumping the entire wiki on someone before they’ve touched the codebase produces the opposite of the intended effect – none of it sticks because there’s no context to hang it on yet. Point to documentation exactly when it becomes relevant: the deploy doc when they’re about to deploy something, the data model doc when their first ticket touches the data model. Ten pages read at the moment they matter beat a hundred pages read cold on day one.
Ask them what was confusing, while it’s still fresh
By the end of week one, the new hire is the only person on the team who still remembers what it’s like to not know how anything works – that perspective is gone within a month, replaced by the same blind spots everyone else has. Ask directly: what took longer than it should have, what documentation was missing or wrong, what question did you not want to ask. Fix the concrete ones before the next hire starts. This is the cheapest source of onboarding improvements you’ll ever get, and it disappears if you wait.
Give environment parity a real check
A surprising amount of “it works on my machine” friction during onboarding traces back to local environments quietly drifting from production – different config defaults, different service versions, dependencies installed in a different order months apart. The twelve-factor app’s argument for keeping dev, staging, and production as similar as possible is worth revisiting through this lens: a new hire’s local setup is the newest test of whether that parity actually holds (12factor.net/dev-prod-parity).
By the end of the week
A realistic bar for day five: one merged PR beyond the day-one trivial one, a written map they’ve read and can navigate from, and a specific person they know to ask instead of guessing who’s least busy. That’s not full productivity – nobody hits that in a week – but it’s enough that the second week starts with real work instead of more discovery.