When an outside engineer takes a month to become useful, the assumption is that the codebase is complicated. Occasionally that is true. More often the engineer spent week one waiting for a repository invitation, week two discovering that the setup instructions describe a system that no longer exists, and week three looking for someone who can explain why an order can have two statuses at once. That is not a property of the code. It is a property of the preparation, which is yours to control.
The day-one test
There is one target worth setting for the first day: a new engineer should check out the repository, build it, run it locally, make a trivial change, and get that change deployed to a non-production environment before they log off. The change itself does not matter: a corrected label, a log line. What matters is that the whole path from an empty machine to running code has been traversed once, by them, without anyone rescuing them halfway.
That one metric predicts everything else, because passing it requires a long list of other things to already be true. Access was granted in advance. The build is reproducible rather than dependent on a machine someone configured by hand two years ago. A non-production environment exists with a deployment path a new person can use without a gatekeeper. The test suite runs. Teams that fail this test are rarely failing at onboarding; they are discovering that their own engineers have carried undocumented setup knowledge for years.
What to have ready before the start date
The most expensive ramp delay is the one where the engineer is available, willing, and blocked on a request in someone else's queue. Access provisioning is the usual culprit, and it is entirely schedulable. Treat the start date as the deadline for the following.
- 1
Signed agreement, confidentiality terms, and intellectual property assignment complete, before any credential is issued.
- 2
Identity account created, multi-factor authentication enrolled, and an expiry date set to match the engagement end.
- 3
Source control access to the repositories in scope, at the permission level the work requires and no higher.
- 4
Access to the issue tracker, design assets, and the channel where the team actually talks, plus any third-party accounts the work depends on. Ask for these early, because external approval cycles are the slowest item here.
- 5
Non-production environment credentials, seeded with representative but non-sensitive data. Never hand over production data as a convenience.
- 6
A named domain contact and a named technical contact, both told in advance that they have been named.
- 7
A first task written up and waiting in the tracker with enough context to start on it.
- 8
A day-one working session with an existing engineer, scheduled to end after the first deployment rather than after a tour of the architecture.
These costs compound. An engineer blocked on environment access reads code they cannot run, forms theories they cannot test, and arrives at the first real task with confident misunderstandings that then have to be unwound in review.
| Blocker | Typical cost | How to remove it before day one |
|---|---|---|
| Access requests filed on the first day | 3–7 days of paid time at partial or zero productivity | Run provisioning off the signed start date. A missing credential on day one is a scheduling failure, not a ticket. |
| Setup instructions that no longer work | 1–3 days, plus interrupted senior engineer time | Have someone who has never built the system follow the README exactly and fix every step that fails. |
| No non-production environment they can deploy to | Ongoing; every change needs a gatekeeper and review cycles stretch | Confirm a shared non-production environment exists and give the engineer a self-service path to it. |
| Domain questions with no clear owner | The largest single source of rework in the first month | Name one person, tell them they are named, and agree a response expectation in business days. |
| A first task that is either trivial or enormous | 1–2 weeks of low-signal work, or an unreviewable first pull request | Pick a real, small, user-visible change in the area the engagement will focus on. |
| Secrets shared over chat or email | A security incident with a long tail and no clean revocation | Use a secret manager with per-person access and an expiry. Decide the rule before someone improvises one. |
A README that has actually been followed
Most teams have documentation. Very little of it is verified. Documentation nobody reads describes the system as its authors understand it (architecture diagrams, a list of services) while omitting the specific commands that turn an empty laptop into a running application. A working README has been followed end to end, recently, by someone with no prior context, and every step they got stuck on was fixed rather than explained away in a chat thread.
The verification is the exercise. Hand the document to someone who has not set this project up before, with no help, and record where they stop. Do not answer their questions in the moment; write the answer into the file instead.
- Exact prerequisites with versions, and how to check what is installed
- The literal commands to install dependencies, configure the environment, seed data, and start the application
- How to run the test suite, and what a passing run looks like
- How to deploy to the non-production environment, and who to ask when a deploy fails
- The domain terms that mean something specific in this business, and where the real business rules live
A first task that is real and low-risk
The instinct is to protect a new engineer from anything consequential, so the first task becomes a sandbox exercise, a documentation pass, or a bug so trivial it teaches nothing. All three waste the most attentive week you will get from them. The opposite failure is handing over a subsystem rewrite because the engagement is short and the backlog is long, which produces a first pull request nobody can review.
The right first task is real production code, small enough to finish in a day or two, in the area the engagement will focus on, with a visible outcome and an obvious way to undo it. It should exercise the full path (change, test, review, deploy) because the purpose is to validate the path as much as the change.
- Real: it ships, and someone notices if it is wrong
- Small: finishable in a day or two, reviewable in fifteen minutes
- Relevant: in the part of the system the engagement is about
- Reversible: a single revert restores the previous behavior
One named person for domain questions
Outside engineers can read code without help. What they cannot do is work out why a shipment can be closed before it is invoiced, or which of the three customer tables is the one that matters. Those answers exist only in someone's head, and the speed of getting them sets ramp time.
Name one person. Tell them they have been named, agree what a reasonable response time is, and protect the time it takes, usually a few hours a week at the start. A single named contact beats an open channel, because a new engineer asking six people gets six partial answers and no way to reconcile them.
Access decisions for people who are not employees
Contractors are a normal part of software delivery and should be given the access their work requires. They should not inherit the standing access an employee accumulates over years, and where the line sits should be decided at the start rather than case by case under delivery pressure. Grant least privilege, and make every grant time-bound.
| Access | Sensible default | At the end of the engagement |
|---|---|---|
| Source control | Write access to in-scope repositories only, no administrative or organization-wide rights | Remove from the organization; rotate deploy keys and tokens they held |
| Production data | No direct access. Work against seeded or anonymized data in a non-production environment | Nothing to revoke, which is the point of the default |
| Production systems | Read-only observability where debugging requires it; deployment through the pipeline, not console access | Revoke accounts and confirm no standing credentials remain |
| Secrets and credentials | Issued per person through a secret manager with an expiry, never shared through chat or email | Expire and rotate every secret they could have read |
| Third-party accounts | Individual named accounts, never a shared login | Deactivate the named account; audit for shared logins created as a shortcut |
Write the revocation steps down while the access is being granted, because that is the only moment anyone has a complete picture of what was issued. Offboarding reconstructed from memory months later reliably misses the shared vendor login and the token pasted into a chat thread.
Review that catches misunderstanding early
The purpose of reviewing an outside engineer's first few changes is not to check their competence. It is to catch where they solved the problem you described rather than the problem you have. Those divergences are cheap to fix in the first week and expensive in the third.
Automated gates do the low-value half of this for free. Formatting, static analysis, and a test suite that must pass before a merge remove an entire category of review comment, along with the awkwardness of a new person being corrected on things a tool should have caught. What is left for a human is the part that matters: is this the right change, in the right place.
- Review the first two or three changes within hours, not days, because the feedback loop is the deliverable
- Require a short written statement of intent on each pull request, so a misread requirement is visible before the code is read
- Enforce formatting, linting, and tests in the pipeline so review conversation stays on design and domain
- Say what the convention is and why, not just that the change is wrong
- Taper deliberately once two or three changes land cleanly, and stop spending senior time on it
None of this is specific to contractors; it makes onboarding faster for permanent hires too. It gets built for outside engineers first only because the cost is visible, arriving as an invoice rather than disappearing into a salary.
Common questions
- How long should ramp time actually take?
- With access provisioned in advance and verified setup documentation, an outside engineer should be running the system on day one and merging a real change within the first week. Meaningful independent work on a normal business system usually starts in week two or three. If it is taking a month, the constraint is almost always access, documentation, or an unanswered domain question rather than the engineer.
- Should contract developers have access to production data?
- Not by default. Give them a non-production environment with seeded or anonymized data that is representative enough to work against, which covers the large majority of development tasks. Where production access is genuinely required for debugging, prefer read-only observability, scope it narrowly, log it, and remove it when the specific need ends.
- What is the single highest-return thing to fix before a contractor starts?
- Have someone who has never set up the project follow the setup instructions on a clean machine, and fix everything that breaks. It is usually a few hours of work and it removes the most common multi-day blocker. It also tells you honestly whether your build is reproducible or depends on undocumented local state.
- Is it worth onboarding an outside engineer for a short engagement?
- It depends on whether ramp cost is a fixed overhead or a one-time investment. If the preparation work exists already, ramp is a few days and a six-week engagement is comfortably worthwhile. If every new engineer rediscovers the same setup problems, you are paying that cost repeatedly, which is an argument for fixing the preparation rather than for avoiding outside help.
- How much of our internal team's time should onboarding consume?
- Plan for a few hours a week from one named domain contact for the first two to three weeks, plus fast review turnaround on the first few changes. Budget it explicitly and tell the person it is part of their job for that period. Onboarding that is assumed to happen in spare capacity is the most common reason ramp stretches into a second month.
- What should we do when the engagement ends?
- Work from the access list you wrote when the access was granted, not from memory. Deactivate accounts, remove repository and organization membership, rotate every secret and deploy token the engineer could have read, and check for shared logins created as a shortcut during the work. Confirm that documentation, credentials, and any work in progress have been handed back before the final invoice is settled.