Category: Teams

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 day

Write 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.

Most on-call advice is written for organizations with a dedicated SRE team, a follow-the-sun rotation across three continents, and a dashboard nobody outside the ops team has ever opened. None of that applies when your entire engineering team is five people and everyone also writes features during the day. On-call at that scale needs different rules, or it turns into a tax that burns out whoever’s least willing to push back.

Rotate, even if it feels unnecessary

The instinct on a small team is to let whoever built a feature handle its incidents, since they know it best. This seems efficient and quietly turns into a problem: one person becomes the permanent safety net, gets paged constantly, and everyone else’s incident-response skills atrophy. Put a real rotation in place even at five people – a week each, or two if pages are rare. The person on call that week owns everything, not just their own code. This forces documentation and runbooks to exist, because the person responding won’t always be the author.

Write down what “page me” means

Vague escalation criteria are the fastest way to make on-call miserable. If every anomaly pages someone at 2 a.m., people learn to ignore pages, which defeats the point. Define a short list of conditions that justify a page – user-facing outage, data loss risk, authentication failures, error rate above a hard threshold – and route everything else to a ticket that gets triaged in the morning.

Page immediately:
- API error rate > 5% for 5+ minutes
- Any 5xx spike on checkout or login
- Database replica lag > 60s
- Background job queue depth growing unbounded

File a ticket, no page:
- Single failed job with automatic retry succeeding
- Non-critical third-party API degraded
- Elevated latency within SLA

Google’s SRE book has a chapter specifically on what makes on-call sustainable, and the core idea holds at any team size: a page should always be actionable and should always matter (sre.google/sre-book – being on call).

Budget for the interruption, not just the response

A page at 3 a.m. doesn’t just cost the ten minutes spent fixing the issue – it costs the rest of that person’s next day, when they’re running on four hours of sleep and shouldn’t be reviewing anything sensitive. On a small team, build this into planning explicitly: whoever was on call and got paged overnight doesn’t owe a full day of output the next morning. Treating on-call as free capacity is how you lose people.

Tooling doesn’t need to be a budget line

You don’t need an enterprise incident platform to run a five-person rotation well. A free-tier alerting tool wired to your existing monitoring, a shared calendar for who’s on call this week, and a pinned doc with escalation steps covers real needs at this scale. The expensive platforms earn their price once you have dozens of services and multiple teams sharing an escalation policy – below that, the extra configuration surface is often just another thing someone has to maintain instead of ship product.

Keep a running incident log

Even lightweight incidents deserve two sentences in a shared doc: what happened, what fixed it, what would prevent it. At five people you don’t need a formal postmortem template, but you do need a record, because the same failure mode will recur in six months and nobody will remember the fix. This log becomes the seed of your runbooks – the next person on call searches it before paging anyone else.

The habit is worth more than the format. A plain markdown file in the repo, sorted by date, with a one-line summary and a link to the fix, beats an elaborate incident-management tool that nobody updates because logging an entry takes ten clicks instead of one commit.

Make handoff a real conversation

When the rotation changes hands, spend five minutes actually talking – not just a bot message saying “rotation updated.” What’s flaky right now, what’s mid-fix, what alert fired twice this week and might fire again. Atlassian’s guide to on-call health has good language for framing this as a habit rather than a formality (atlassian.com – on-call guide).

Don’t skip the retro because the team is small

It’s tempting to treat a five-minute Slack thread as sufficient after a minor incident, and sometimes it is. But anything that paged more than one person, or took more than thirty minutes to resolve, deserves a real look at why – not to assign blame, there’s nowhere to hide blame on a team this size anyway, but because the same five people will be the ones fixing it again if the root cause never gets addressed.

On-call at five people will never look like on-call at a company with a platform team. That’s fine – the goal isn’t to import a large-company process, it’s to make sure the pager doesn’t quietly become one person’s permanent problem, and that whoever’s holding it knows exactly what deserves to wake them up.