Greenbox delivers weekly produce boxes to 5,000 subscribers across Perth and Melbourne. Brisbane is coming. The team has grown from five to eighteen, and now it needs to grow again, fast. Three new developers start in three consecutive weeks. Nobody is ready for what that does to the team.
Maya posts the hiring plan on a Monday afternoon. Three developers, a second operations person, a dedicated QA. All starting within the next month.
Tom stares at the plan. “Three developers in three weeks?”
“Melbourne needs two. Perth needs a senior to backfill you when you’re doing architecture work. And we need the QA before Brisbane goes live.”
“I’m not arguing the need. I’m arguing the timing.”
Maya doesn’t have a choice. Brisbane’s launch date is fixed. The board approved headcount in a batch because that’s how boards work; they don’t approve one hire at a time, they approve a hiring round. The offers went out. The start dates were negotiated around notice periods. Three developers in three weeks is what the calendar produced.
Tom opens his own calendar and starts counting empty slots. There are four hours unbooked across the entire week. Two of those are lunch.
Week one: Danielle
Danielle starts on Monday. She’s 29, from a mid-size e-commerce company in Sydney. Good references. Solid Rails background, picking up Go. She moved to Perth for her partner’s job and took the Greenbox role because the domain sounded interesting and the interview process was the best she’d experienced.
Tom is her unofficial onboarding buddy, which means Tom is the person she asks when she doesn’t know who to ask. On Monday morning, he walks her through the office, introduces the team, shows her the codebase on his laptop, and gives her the setup instructions.
The setup instructions live in a README that was last updated four months ago. In that time, the team switched from Docker Compose to a custom dev environment script, added three new services, and changed the database seeding process. The README mentions none of this.
Danielle spends Monday afternoon and all of Tuesday trying to get the local environment running. The Docker Compose file references a service that no longer exists. The database seed fails because it expects a table that was renamed in July. She fixes one thing and hits another. She’s good at debugging; that’s not the problem. The problem is that she’s debugging the onboarding process instead of learning the domain.
At 4pm on Tuesday, she messages Tom: “Still can’t get the seed to run. Getting a missing table error on subscription_preferences.”
Tom: “Oh, that got renamed to customer_flags when we did the decision tables. Should be in the migration but the seed script is separate.”
“The seed script references the old name.”
“Right. I’ll fix that.”
He fixes it in ten minutes. Danielle has lost a day and a half.
On Wednesday, Danielle finally has the environment running. Tom walks her through the bounded contexts, twenty minutes at the whiteboard. She takes notes. He shows her the ADRs, which help enormously. ADR-001 about billing on delivery day answers a question she would have got wrong. ADR-013 about feature flags explains a pattern she noticed in the code.
By Friday, Danielle has submitted her first PR. It’s small: a bug fix in the customer notification service. Tom reviews it in the afternoon. The code is fine. She’s clearly competent. But it took five days to get one small PR, and Tom spent roughly six hours of his week on Danielle.
Six hours doesn’t sound like much. But Tom’s week only has forty hours, and twelve of those are already meetings. Twenty-eight hours of available work time, minus six for onboarding. That’s a 21% reduction in Tom’s output for the week. For one new starter.
Week two: Mika and the onboarding tax
Mika starts the following Monday. He’s joining the Melbourne squad remotely from Perth while Anika finds office space. He’s experienced, seven years, mostly in fintech. Quiet, methodical, prefers to read documentation before asking questions.
Mika reads the README. Hits the same Docker Compose problem Danielle hit. Messages Tom.
Tom realises he forgot to merge Danielle’s fix. He merges it, but the seed script issue is only half-fixed: Danielle’s PR addressed one table rename but there are two others.
Mika loses Monday afternoon.
Meanwhile, Danielle has questions. She’s reading the substitution engine code and the decision tables that drive it. The code is excellent but the connection between the tables and the implementation isn’t obvious unless you know the history. She asks Priya.
Priya spends an hour walking Danielle through the substitution flow. It’s a good conversation. Danielle asks sharp questions, and Priya realises how much context she carries that isn’t written down anywhere. But that’s an hour of Priya’s day that wasn’t in her sprint plan.
Tom’s calendar is now fully booked. He’s answering questions from Danielle, onboarding Mika via video call, doing code reviews for both, and trying to keep his own work moving. On Wednesday he stays until 8pm to catch up on the sprint work he’d planned for Monday and Tuesday.
Sarah notices. “You said three new people was going to be fine.”
“It is fine. It’s just a lot this week.”
“You said that last week.”
Tom doesn’t answer because she’s right.
Anika calls from Melbourne. “Mika doesn’t know who to ask about the farm portal. He’s been reading code for two days. He says he doesn’t want to bother anyone.”
“He should bother someone. That’s how onboarding works.”
“He doesn’t know that. Nobody told him it’s okay to interrupt people. At his last company, you got dinged on your review for asking too many questions in your first month.”
Tom closes his eyes. Every new person brings their own history, their own assumptions about how teams work. Mika’s assumption (don’t ask, figure it out) is the opposite of what Greenbox needs. But nobody told him that, because nobody thought to.
Week three: Jordan and the breaking point
Jordan starts the following Monday. They’re the QA hire: Greenbox’s first dedicated tester. They’ve never worked at a startup. Their previous company had 200 developers and a formal onboarding programme with a two-week curriculum, an assigned mentor, a buddy, and a graduation checklist.
Greenbox has none of that.
Jordan asks Tom for the test plan. Tom says there isn’t one. Jordan asks for the test environments. Tom says there’s one shared staging environment. Jordan asks for the testing guidelines. Tom points at the CI pipeline configuration.
“Where’s the onboarding guide for QA?”
“We don’t have one. We’ve never had a QA person before.”
Jordan is polite about it, but the look on their face says everything. They’ve joined a company that hired a QA without thinking about what a QA needs on day one.
By Wednesday of week three, the maths is brutal. Tom is spending roughly twelve hours a week on onboarding. Priya is spending six. Anika is spending four on Mika remotely. The three new people are asking questions faster than the existing team can answer them. And the new people don’t feel good about it either; they feel slow, uncertain, and guilty for consuming everyone’s time.
Danielle, now in her third week, is becoming productive. But her first PR took five days. A developer of her calibre should have shipped something useful in two.
Mika, in his second week, is still mostly reading code. He’s figured out the farm portal on his own, but his understanding has gaps that won’t surface until he builds something on a wrong assumption.
Jordan is writing their own onboarding checklist because nobody else did.
Brooks’s Law, lived
Tom brings it up at the Friday retro. “We’re slower now than we were three weeks ago. Before the new people started, the existing team shipped about fifteen story points per sprint. This sprint we’ll be lucky to hit ten.”
It’s Frederick Brooks’s observation from 1975, in The Mythical Man-Month: adding people to a late project makes it later. The mechanism is communication overhead. Five people have ten communication paths. Eight people have twenty-eight. Fifteen people have a hundred and five. Every new person doesn’t just add their own capacity; they add communication load to everyone already there.
The dip is temporary; that’s the crucial point. Once new people are productive, total capacity is higher than before. But during the absorption period, you go backwards. And if you keep adding people before the previous ones are absorbed, you stay in the dip.
“We’re not late on a project,” Maya says. “We’re scaling a team.”
“Same physics,” Tom replies. “Each new person temporarily reduces total capacity. If you add them faster than the team can absorb them, you go backwards. You stay in the dip.”
Lee, on the call from Margaret River, says quietly: “What if you treated onboarding like a product?”
Onboarding as a product
The idea sits with the team over the weekend.
On Monday, Charlotte picks it up. “A product has users, requirements, success metrics, and iterations. Who are the users of your onboarding?”
“The new people,” Priya says.
“And the existing team. Both groups have needs. The new people need to become productive. The existing team needs to not be crushed by the process. Right now you’re optimising for neither.”
Charlotte suggests three things.
A buddy system. Every new person gets one named buddy for their first month. Not their manager. Not the team lead. A peer who’s been at Greenbox for at least three months. The buddy’s job is defined: one hour per day for the first week, thirty minutes per day for weeks two and three, available on Slack for week four. The buddy’s sprint capacity is reduced by 20% for the month, and the sprint plan accounts for this.
“That’s the key,” Charlotte says. “If you don’t account for the onboarding tax in the sprint plan, you’re lying to yourselves about your capacity.”
An onboarding checklist. Not a README. A checklist: a document that every new person works through, with steps, links, and expected outcomes. It should answer the questions that every new person asks: How do I set up my environment? Where’s the codebase? Who do I ask about what? What are the bounded contexts? Where are the ADRs? How does deployment work? What does the team expect from me in week one, week two, week four?
“Jordan’s already writing one,” Danielle points out. “She started writing it because it didn’t exist.”
Charlotte smiles. “Hire someone from a company with good onboarding and they’ll show you what you’re missing.”
Jordan shares their draft checklist. It’s thorough. Forty-three items across five categories: environment setup, codebase orientation, domain knowledge, team processes, and first tasks. About half of the items have answers. The other half are marked “ask someone, not sure who.”
“Those twenty blanks are your tribal knowledge,” Lee says. “The things that live in people’s heads and nowhere else. Every one of them is a question that every new person will ask, and every time they ask, someone will spend fifteen minutes answering. Write the answers down once.”
Time to first PR as a metric. Danielle’s first PR took five days. Charlotte suggests tracking this for every new hire. Not as a performance measure, but as an onboarding quality measure. If time to first PR is getting longer, the onboarding is getting worse. If it’s getting shorter, the process is improving.
Pair programming as onboarding
Priya suggests something else. “When I walked Danielle through the substitution engine, I realised half of what I was explaining isn’t in the code or the ADRs. It’s the reasoning between decisions. Why this service calls that service. Why the error handling works that way. You can’t write all of that down.”
Her suggestion: pair programming for the first two weeks. New person navigates, experienced person drives. Then swap. The navigator learns the codebase by watching someone who knows it. The driver learns what’s unclear by watching someone struggle with it.
Lee backs her up. “Pairing isn’t just a teaching tool. It’s a knowledge extraction tool. The experienced person discovers what they know implicitly, because the new person asks about the things the experienced person has stopped noticing.”
They try it with Mika the next morning. Priya drives, Mika navigates. She’s implementing a new farm availability endpoint. Mika asks why she’s putting the validation in the service layer instead of the handler.
“Because the handler might change when we add the API gateway, but the validation rules won’t. It’s in…” she pauses. “Actually, I don’t think we wrote an ADR for that. We just always do it that way.”
“Should we write one?”
“Yes. Let’s do that now.”
Thirty minutes of pairing produces a working endpoint and a new ADR. The pairing didn’t slow Priya down; it surfaced an undocumented convention and created an artifact that will help every future developer.
After lunch, they swap. Mika drives, Priya navigates. He’s visibly more confident. He knows where the validation goes. He asks about the error response format and Priya points him to the API conventions doc, which, she discovers, is also out of date. She updates it while Mika writes the handler.
The third starter’s better week
Two weeks later, a fourth developer starts. Nina, joining the Brisbane squad. She’s the first person to go through the new onboarding process.
Day one: Nina’s buddy is Danielle, who started five weeks earlier. Danielle remembers exactly what was confusing because she was confused five weeks ago. She walks Nina through the checklist. The environment setup (now documented accurately) takes ninety minutes instead of two days. The bounded context tour, with ADRs and decision tables linked at each step, takes an hour.
Day two: Nina pairs with Ravi on the subscription service. She navigates, he drives. By lunch she understands the billing flow. After lunch they swap. She implements a small feature (a subscription summary endpoint) with Ravi watching.
Day three: Nina submits her first PR. Two days. Danielle took five. Mika took seven.
It’s not that Nina is a better developer. It’s that the onboarding is better. The checklist answered the questions she would have asked. The pairing gave her context that documentation can’t fully capture. The buddy system meant she always knew who to interrupt.
Documentation for newcomers vs documentation for experts
The onboarding process surfaces an uncomfortable truth: most of Greenbox’s documentation was written by experts for experts.
The ADRs are excellent, for someone who already understands the domain. ADR-001 explains why billing happens on delivery day. But a new developer doesn’t know what “delivery day” means in the Greenbox context, or that box contents vary weekly, or that the supply matching happens on Tuesday. The ADR assumes you already know the domain. If you don’t, it’s a paragraph of correct information that you can’t fully absorb.
Jordan puts it bluntly: “Your docs explain the ‘why’ to people who already understand the ‘what.’ New people need the ‘what’ first.”
The team creates a separate newcomer’s guide: not a replacement for the ADRs and decision tables, but a prerequisite. It starts with what Greenbox does. Farms supply produce. The system matches supply to demand weekly. Boxes are packed and delivered. Customers subscribe. Here’s the weekly cycle. Here’s who does what. Here’s where the code lives. Here’s what happens on Tuesday (supply matching), Thursday (delivery), and Friday (retro). Here’s who to ask about billing, about the farm portal, about the substitution engine, about deployment.
It reads like a letter to a stranger. Because that’s what it is.
Charlotte calls it the “twenty-minute overview”: the document a new person reads on their first morning that gives them enough context to make sense of everything that follows. Without it, the ADRs are chapters in a book whose first page is missing.
It’s the kind of document that feels too basic to write; everyone on the team already knows this. But “everyone on the team” is a group that changes every month. The knowledge that feels obvious to twelve people is invisible to the thirteenth.
The steady hire
Lee raises one more point at the retro. “You’ve now experienced what happens when you hire in bursts. Three people in three weeks overloaded the system. What if you’d hired one person per month instead?”
“The board approved the headcount as a batch,” Maya says.
“Approved headcount and start dates are different things. You could have staggered the starts. One in September, one in October, one in November. Same three hires. Same total cost. But each person gets a team that isn’t already saturated.”
Maya writes it down. It’s such a simple idea. Stagger the starts. Hire steadily, not in bursts. Let each new person become an onboarding resource for the next one.
“Danielle onboarded Nina,” Lee continues. “Five weeks in, she was the best possible buddy, because she remembered what it was like to not know. That only works if there’s enough gap between arrivals for the previous person to settle.”
What stuck
Three months later, the onboarding process is unrecognisable from what Danielle walked into.
The checklist has been through four iterations. Each new starter adds the things that tripped them up and removes the things that were unnecessary. It’s a living document, and its best editors are the people who most recently used it.
Time to first PR has dropped from five days to two. Not because the new hires are better, but because the onboarding is.
The buddy system is standard. Sprint plans account for a 20% capacity reduction for anyone buddying a new starter. This feels expensive until you compare it to the alternative: an unplanned 40% reduction when everyone answers questions ad hoc.
Pairing is how new people learn the codebase. It’s slower than reading code alone on day one. It’s faster by day five.
Jordan’s QA onboarding guide, the one they wrote because nobody else had, becomes the template for role-specific onboarding tracks. Developers get one path. QA gets another. Operations gets a third. All share the same first section (what Greenbox does, how the weekly cycle works, where the code lives) and then diverge.
And the tribal knowledge that lived in people’s heads? Some of it got written down. The rest got surfaced in pairing sessions, where it could be shared even if it couldn’t be fully documented. The team accepted that not everything can be a document. Some knowledge transfers only through working together.
The thing nobody says
Danielle is reviewing Nina’s second PR when she pauses. The code is clean. The tests are thorough. Nina understood the domain constraints without being told, because the onboarding taught her.
Danielle remembers her own first week. The broken README. The renamed table. The two days lost to environment setup. She doesn’t feel resentful about it. She feels something closer to protectiveness, a determination that nobody else should have to go through what she went through.
That’s the real output of good onboarding. Not efficiency. Not faster time-to-PR. The feeling, in a new person, that the team was ready for them. That they were expected. That the organisation invested time in their success before they proved anything.
Tom catches Danielle in the kitchen that afternoon. “Thanks for buddying Nina. She’s already contributing.”
“The checklist did most of the work.”
“You wrote half the checklist.”
Danielle shrugs. “I just wrote down everything I wish someone had told me.”
That’s the whole trick, really. Onboarding isn’t a process that someone designs from above. It’s the accumulated memory of everyone who was ever new, preserved so the next person doesn’t start from zero.