A week is a real target, and it is mostly about you
The instinct is to treat ramp time as a property of the engineer. It is mostly a property of the company. Two engineers of identical skill will hit their first merged change on day three at one company and day nineteen at another, and the difference is not talent. It is whether a laptop could get credentials on Monday, whether the application ran locally without a two-day archaeology project, and whether somebody was willing to answer questions in writing within a few hours.
This is genuinely good news, because it means the ramp is controllable. It is a preparation problem rather than a hiring problem, most of the preparation can be done before a contract is signed, and all of it has value even if the engagement never happens. A company that can onboard an outsider in five days can also onboard a new employee in five days, and can rebuild its own production environment when something breaks at an inconvenient hour.
Two honest caveats before the specifics. A week gets you a working engineer, not a knowledgeable one — the difference matters and we come back to it. And in regulated environments, background checks and formal access approvals can add one to three weeks that no amount of preparation shortens. If that applies to you, start the paperwork the day you start the conversation, not the day you sign.
You are probably here because
- The last contractor spent two weeks trying to get the app to run
- You are about to sign and want to know what to prepare
- Somebody asked what access an outside engineer needs and you do not have a list
- You suspect your own new hires take too long to become useful, and you are right
The access list and the one-command environment standard are the two sections that decide the outcome. Everything else is scheduling.
What productive means on day five
Set the target precisely, because a vague target produces a vague week. On day five a well-onboarded outside engineer has done four things: run the system locally or in a working development environment, read enough of the code to describe the main flow without help, merged a small but real change, and watched that change reach a deployed environment.
Notice what is not on that list. They do not understand the domain. They do not know why the pricing module has that exception for accounts created before 2021. They cannot yet be trusted to estimate. Those come later, and they come through work rather than through documents. The week-one goal is to prove the path from a text editor to production is open, so that from day six onward the only remaining variable is the work itself.
A useful way to hold it: week one buys you a functioning engineer, weeks two through five buy you a productive one, and weeks six onward buy you someone with judgment about your system. Anyone promising judgment in week one is describing a different, smaller system than the one you have.
The five things that block a week, in order
Ranked by how often we watch each one eat days. The order is stable across company sizes and it surprises people, because the things at the top are administrative and the things people worry about are at the bottom.
One: access. Not the decision to grant it — the mechanics. A repository invitation to an email address that is not in the directory. A single sign-on tenant that will not create an external identity without a security review. A cloud role that requires an approval from someone on holiday. A password manager vault that only two people can share. Access is administrative, boring, and routinely eats three of the five days. It is also entirely preventable by starting it a week early.
Two: the environment will not come up. The README is eighteen months old. Two services are missing from the compose file. A required data seed lives on somebody's laptop. An environment variable is undocumented and its value is in a chat message from last year. This is the most demoralizing failure mode because it produces days of work with nothing to show, and because it tells the engineer something discouraging about the codebase before they have read any of it.
Three: nobody is designated to answer questions. When questions route to “whoever is free,” they route to nobody and pile up in a channel until a meeting can be scheduled. One named person with a two-to-four-hour response commitment is worth more than any document.
Four: no definition of the first task. An engineer who is fully set up and has no clearly bounded first task will spend the day reading and produce nothing observable, which starts an engagement on a note of unease that takes weeks to repair.
Five: unwritten conventions. Branch naming, commit style, the review rule, the deploy window, whether migrations go in the same pull request. Small individually, and collectively they generate a week of tiny corrections that make everyone feel the engagement is going badly when it is only uncalibrated.
| Day | What should happen | Who owns it |
|---|---|---|
| Before day one | Access requested, environment instructions tested by someone who has not run them before, first task written down | You |
| Day one | Accounts live, repository cloned, application running locally, thirty-minute walkthrough of the main flow | You, with the named owner |
| Day two | Tests run green locally, engineer reads the code path for the first task, writes questions down | Engineer |
| Day three | First pull request opened — small, real, reviewable in fifteen minutes | Engineer |
| Day four | Review turned around same day, merged, deployed to a non-production environment | You |
| Day five | Written summary: what was learned, what is unclear, what the engineer thinks is risky | Engineer |
The environment is the whole game
If there is one thing to fix before anybody arrives, it is that a new machine can get the system running with a short, documented sequence of commands. Not a wiki page with fourteen manual steps and a footnote about a certificate. A checked-in script, or a container definition, or a devcontainer, that a person who has never seen the project can execute and end up with something running.
The test is specific and you can run it this week without hiring anyone: hand your setup instructions to an engineer on a different team who has never touched this project, give them a fresh machine or a clean container, and watch without helping. Time it. Write down every place they get stuck. That list is your onboarding backlog, it is usually two to four items long, and fixing it takes one to three days.
Two adjacent things matter almost as much. The first is seed data. A running application with an empty database is not a running application; it is a login screen. A small, safe, checked-in dataset that exercises the main paths turns day two from guesswork into work. The second is that the test suite should pass on a clean checkout. A suite that fails three tests on everyone's machine, which the team has learned to ignore, gives a newcomer no signal at all about whether their own change broke something.
None of this is a large project. In most companies it is a few days of unexciting work that has been deferred for a year because it never had a deadline. Bringing in an outsider gives it one.
The access list, sent before day one
Send this as a list, with a named owner and a date next to each item, the day the engagement is agreed. Almost all of it can be started before signature, and the ones that cannot are the ones worth knowing about early.
Source control on the specific repositories, with permission to open branches and pull requests. An identity in your directory, because a guest account that cannot access anything else is a week of tickets waiting to happen. The issue tracker, with permission to comment and change status, not read-only. Continuous integration, so failures can be read rather than relayed. A non-production environment with the right to deploy to it, which is the single most commonly forgotten item on this list. Logs and error monitoring, because an engineer who cannot see an error is guessing. Secrets for local development, delivered through the password manager rather than a chat message. Any third-party service the code talks to, in a sandbox tier. The chat channel where the work is discussed, and the calendar of whatever standing meeting matters.
Production access is the one to think about rather than default. Most outside engineering work does not need it, and read-only production access with an audit trail covers the majority of the legitimate cases. If the answer is no, say so on day one and make sure there is a way to get logs and reproduce issues without it — an engineer who cannot see production and cannot get its errors is being asked to debug blindfolded, and will bill you for the blindfold.
What predicts a fast ramp — our read
Our judgment from repeated first weeks, not a survey. The last row surprises people: documentation helps, but a runnable environment beats a long wiki every time.
One person, answering in writing
The single most useful assignment you make is a named owner for questions, with an explicit response window — two to four hours during the first week is right. It does not have to be your most senior engineer, and it usually should not be. It has to be somebody who knows the system and can be interrupted.
Ask for questions in writing, in a shared channel, and answer them there. This does two things at once. It removes the scheduling problem, which is the actual cost of question-answering across organizations, and it produces documentation as a by-product. The questions an outsider asks in week one are precisely the questions your next hire will ask, and the answers, written once in a channel, are worth more than the onboarding document nobody has updated since the reorganization.
Batching helps both sides. An engineer who saves non-blocking questions for one message a day, and flags the genuinely blocking ones immediately, imposes a fraction of the cost. That is a reasonable thing to ask a vendor for, and any decent one already works that way.
Choose the first task rather than grabbing one
The first task is a diagnostic, not a contribution. Choose it deliberately with four properties: it touches the part of the system the engagement is actually about, it is small enough to finish in a day, it has an obvious correctness test, and it will not be embarrassing if it takes three days because something unexpected got in the way.
Good candidates look like adding a field through an existing flow, fixing a small well-specified bug in the relevant module, adding tests to a component the engagement will change, or building a small internal endpoint. Bad candidates look like the hardest open bug, anything in the module nobody understands, or a task whose acceptance depends on a conversation with a stakeholder who is travelling.
There is a temptation to give the outsider the nastiest item in the backlog, because that is where the pain is and they are being paid well. Resist it for one week. You learn more about whether this is going to work by watching a small change move cleanly through your whole pipeline than by watching a smart person disappear into a swamp.
What a week does not buy
It does not buy domain knowledge. Why a certain customer type is billed differently, which integration is fragile, what the sales team promised in March — that arrives over months, through work and through being present when things break.
It does not buy reliable estimates. An engineer four days into a system will produce estimates with an error range wide enough to be useless. Asking for them anyway teaches them that the honest answer is unwelcome, which is an expensive lesson to teach in week one.
It does not buy architectural opinions worth acting on yet. A newcomer will notice real things and will also mistake deliberate decisions for accidents. The right protocol is to write the observations down in week one and revisit them in week six, when there is enough context to tell the two apart. Good firms do this on their own; it is fair to ask for it explicitly.
The mistakes we see most
- Starting access provisioning on day one instead of the day the engagement was agreed
- Setup instructions nobody has followed from a clean machine in a year
- No named question-answerer, so everything waits for a meeting
- Scheduling six introduction meetings in a week that needed one walkthrough and quiet
- Giving the hardest open bug as the first task to prove the money was worth it
- A test suite that fails on everyone's machine, so a newcomer gets no signal from it
- Withholding a deploy target, so the first change cannot be watched all the way through
- Asking for an estimate on day four and treating the answer as a commitment
When a week is not possible, and what that tells you
Some systems cannot be onboarded in a week, and it is worth naming them honestly because the diagnosis is more valuable than the schedule.
If the system only runs on one specific machine that a specific person configured, you do not have an onboarding problem, you have a continuity problem, and it is larger than this engagement. If the build depends on a service that no longer exists in a supported version, that is a project rather than a setup step. If nobody currently at the company has deployed the system end to end, the honest first engagement is to establish that path, and it is a good use of outside money.
In each of these cases, the useful move is to make the first week's deliverable the environment itself: a documented, reproducible way to run and deploy the system, checked into the repository. That is worth paying for on its own, it makes every subsequent week cheaper, and it is the only version of this work that leaves the company better off if the engagement ends early.
Before day one
- Access list written, with an owner and a date on every line
- Setup instructions tested from a clean machine by someone unfamiliar with the project
- Seed data checked in, small and safe
- Test suite green on a fresh checkout
- One named person for questions, with a stated response window
- A first task chosen, written down, with a correctness test
- A non-production environment the engineer may deploy to
- Conventions written in one short page: branches, reviews, migrations, deploy windows
- A day-five written summary expected, and a slot to read it
Bottom line
Ramp time is a property of the company far more than the engineer, which means it is under your control and can be shortened before anyone signs anything. Get access started early, make the environment come up from a clean machine, name one person to answer questions in writing, and choose a small first task deliberately. Do those four things and a week is a comfortable target rather than an ambitious one. Skip them and you will pay senior rates for an engineer reading a stale wiki page, which is the most expensive form of nothing available. The preparation is worth doing regardless of whether you ever hire an outside firm, and that is the strongest argument for doing it now.
Frequently asked questions
For a merged and deployed small change, often yes, because that milestone depends on the pipeline rather than on the size of the codebase. For meaningful work inside a large legacy system, plan on three to six weeks. The useful move is to keep the week-one target as it is — prove the path from editor to production works — and set separate expectations for the first substantial contribution.
Usually not, and usually they do not need it. Read-only production access with an audit trail covers most legitimate cases, and a non-production environment they can deploy to covers the rest. What is not acceptable is denying both production visibility and a way to reproduce issues, because that leaves an engineer debugging from descriptions. Decide it on day one rather than discovering it in week three.
Budget four to eight hours from the named question-answerer across the week, plus an hour or two of walkthrough time and same-day code review. That is a real cost and it lands on someone who is probably already busy. It also drops sharply after week one if the questions were answered in writing where they can be found again.
Proceed anyway. Documentation is the weakest predictor of a fast ramp on our list. A runnable environment, granted access, and a person who answers questions beat a large wiki comfortably. The practical approach is to write the answers to week-one questions as they are asked, in the channel, and let that become the document you never had.
Most of it, yes, and it usually should. Access requests, environment testing, seed data and the first-task definition are all internal work that costs nothing and has value regardless. The parts that need a signature are the access grants themselves and anything covered by a confidentiality agreement. Starting the internal half a week early is the cheapest schedule improvement available.