Onboarding a subcontract engineer in three days

Where the three weeks usually go

It's rarely the code. It's waiting for access, guessing at vocabulary, and not knowing who to ask.

An engineer who can't run the project locally cannot do anything useful, and that's frequently day one through three on its own. An engineer who doesn't know that "account" means something different in your domain than in the codebase will write correct code that does the wrong thing. And an engineer who has to wait a day for every answer works at a fraction of their rate.

All three are preparable in about two hours of somebody's time before the engagement starts.

The four things to prepare

1. Repository access and a local environment that actually runs

Not just the repo. A README that works, on a clean machine, without tribal knowledge. Seed data or a way to get some. Environment variables documented, with a sample file.

The test: could somebody clone it and have it running in under an hour with no help. If the answer is no, that's the first day of the engagement and you're paying for it.

2. One page on the domain vocabulary

The ten to twenty words your team uses that don't mean what an outsider would assume. What's a "job", a "case", an "account", a "run". Where the codebase name differs from the business name, which is extremely common and a reliable source of subtle bugs.

This page is the highest-value document in the whole onboarding and it usually doesn't exist because everybody internal already knows it.

3. The first ticket, already scoped

Small, real, and touching one part of the system. Not a warm-up task with no value, which wastes a day and signals that you don't have real work ready. Not a large feature either, which produces a week of work before anybody sees whether the collaboration functions.

Something that takes a competent engineer half a day and ships.

4. A named person who answers questions

One person, available for short questions, for the first week. Not a channel, not a rota. Somebody who can answer "which of these two services owns the customer record" in thirty seconds instead of the engineer spending an hour reading.

Budget about an hour a day of that person's time for the first three days. It's the cheapest acceleration available.

The two things to skip

The full architecture walkthrough on day one. Ninety minutes of diagrams before the engineer has touched anything. Almost none of it is retained, because there's nothing to attach it to yet. Do it at the end of week one, when they've been in three parts of the system and the diagram answers questions they've actually formed.

The historical context. Why the previous team made a decision, what the old system did, the migration that went badly. It's genuinely useful and it's useless in week one. Save it for when they hit the thing it explains.

What day one to three should look like

Day one. Environment running before lunch. Domain vocabulary page read. First ticket started. One conversation with the named person, twenty minutes, about the shape of the system rather than the detail.

Day two. First ticket finished and in review. That review is the important artefact, because it surfaces the conventions nobody wrote down, and it does it against real code rather than in the abstract.

Day three. Second ticket, larger, and the engineer starts asking questions that indicate they've built a model of the system. If they're asking about edge cases by day three, onboarding worked.

The signal that it isn't working

By the end of day three, the engineer should be asking specific questions. If the questions are still general, the domain vocabulary wasn't clear enough, or the first ticket was too isolated to teach anything.

That's fixable on day four and expensive to notice on day fifteen.