How to Give a New Developer Enough Context Without a Two-Week Onboarding

The new developer starts on a Monday. By Wednesday they have read the architecture doc, the deployment doc, the style guide, the Q3 retro notes, and a Confluence page called "Misc Gotchas" that was last edited by someone who left the company fourteen months ago. They have opened forty tabs. They have not written a line of code. On Thursday they ask a question in Slack that is answered, three hours later, by someone who was in a different timezone and had already answered it in a doc the new person hadn't found yet.

This is not a training problem. It is a packaging problem. Most onboarding fails not because the information is missing but because it is all given at once, undifferentiated, so the new person can't tell the one fact that will save them a day from the one fact that is historical trivia.

The dump is not generous, it's a chore you're handing off

I used to think a thorough wiki was a kindness. Six months into running delivery for a small agency, I watched a contractor spend an entire first day reading our "Engineering Handbook" — forty-plus pages written over two years by four different people, half of it describing a deploy process we'd replaced in March. He didn't know what was current. Neither, frankly, did we, until he asked.

A documentation dump feels responsible because it's complete. But completeness is the wrong goal for someone's first week. Their actual job that week is narrow: get the environment running, make one small real change, ship it, and understand who to ask when something doesn't make sense. Everything else is reference material they'll find when they need it, not before.

Fast onboarding is curated context, not more context

Here is the bundle I now hand a new developer before their first standup. It fits on one page. If it doesn't fit on one page, something in it is reference material pretending to be orientation.

THE ONBOARDING PACKET

1. Product map (5-8 sentences)
   What the product does, who uses it, and the two or three
   things that would be a disaster if they broke.

2. Current state (what's true right now)
   What's in progress, what's frozen, what's about to change.
   Not the roadmap. This week.

3. Environments
   Names and purposes of each environment (local, staging,
   production), and which one is safe to break.

4. Deployment path
   Who deploys, how often, and what has to be true before
   a change goes out. Not the full CI config — the shape of it.

5. Ownership
   Who owns which part of the codebase or which project.
   Not a chart. A list: "billing is Marcus, the mobile app
   is Priya, ask either of us if you're not sure."

6. Naming conventions
   The three or four conventions that, if violated, cause a
   review comment every time. Branch names, ticket prefixes,
   whatever actually gets flagged.

7. Known landmines
   The two or three things that look fine and aren't. The
   endpoint that's slower than it looks. The table you don't
   touch without asking. The test suite that's flaky on
   Tuesdays for a reason nobody's fixed.

8. First task
   One real, small, shippable piece of work. Not a toy repo.
   Not "read the codebase." Something that touches the actual
   system and produces a real pull request by day two or three.

Notice what's missing: history. Why we chose this framework over that one two years ago, who argued for what, the post-mortem from the outage in 2022. That material exists, and it's worth having somewhere, but it's not day-one material. It's the kind of thing you link to, not the kind of thing you lead with.

What a real first week looks like

Monday morning, the new developer gets the packet and thirty minutes with whoever owns the area they're joining. Not a tour of the whole codebase — a walk through the eight items, in order, with room to ask "wait, what's the landmine thing about" out loud instead of discovering it by breaking something.

Monday afternoon, they get the environment running. If the packet's deployment section was honest, this takes an hour, not a day. If it takes a day, that's useful information too: it tells you the packet is wrong somewhere, and you fix the packet, not just that one person's setup.

Tuesday, they start the first task. It should be real enough that merging it means something, and small enough that getting it wrong doesn't cost the team a week. A copy fix that touches the actual deploy pipeline is better than a perfect toy project, because it proves the whole path — code, review, deploy — actually works end to end, for them, on their machine, with their credentials.

By Thursday or Friday, that first pull request is in. This is the real milestone of onboarding, not "has read the handbook." A shipped change, however small, tells you the environment works, the ownership list was accurate enough to get a review, and the landmines section didn't have a gap.

Where the rest of the context lives

The handbook, the retro notes, the architecture decision records — keep them. They're not wrong to have; they're wrong to lead with. We keep ours as documents scoped to the project they're about, so a developer working on billing finds the billing history attached to the billing project instead of buried in a company-wide wiki they have to search blind. The point isn't to delete institutional memory. It's to stop making a new hire read all of it before they're allowed to be useful.

If you're writing the packet for the first time, resist the urge to make it exhaustive. Write the eight sections from memory, in one sitting, for the project you know best. If you find yourself writing a ninth section, ask whether it's orientation or reference — and if it's reference, it belongs somewhere a person can find later, not something you hand them before they've typed a single line.