arrow_backAll articles

Developer onboarding: how to get a new programmer productive fast, without chaos

· Josef Chmel

Developer onboarding: how to get a new programmer productive fast, without chaos

A new developer is expensive until they ramp up. What slows them down most according to research from Google and Microsoft, what actually helps, and how to plan their first month.

Finding a good developer takes effort. But it doesn't end when the contract is signed: until the new person finds their way around the code, the tools and the way the team works, you pay a full salary for a fraction of the output, plus the time of the seniors helping them. Developer onboarding is therefore not an HR formality but one of the cheapest investments the head of a software company can make. Let's look at what research teams at Google and Microsoft found about onboarding programmers and how to turn it into a practical plan.

What slows new developers down the most

Researchers at Google (Collin Green, Ciera Jaspan and colleagues) studied how developers ramp up and summarized the results in IEEE Software. The top three hindrances to ramping up were:

  1. learning a new technology,
  2. poor or missing documentation,
  3. finding expertise, i.e. the people who know a given area.

The second finding is uncomfortable for companies with remote staff: after the shift to remote onboarding, engineers ramped up three to six weeks slower.

Google research: the top three hindrances when a developer ramps up, and 3–6 weeks slower ramp-up when onboarding remotely

Notice that two of the three hindrances are not technical. Documentation and "who do I ask" are problems of the organization, not of the new hire. And those are exactly the ones a manager controls.

What actually helps: a mentor, documentation and rising difficulty

A Microsoft team (An Ju, Hitesh Sajnani, Scot Kelly and Kim Herzig) interviewed 32 developers who had recently joined a new team and 15 managers. They then validated the results with a survey answered by 189 developers and 37 managers. The study was published at ICSE 2021.

Three findings are worth remembering:

  • Mentors work. Of the 18 participants who had a mentor or an "onboarding buddy", 14 found them helpful. Those without one said they wished they had someone to sit down with.
  • Documentation is the foundation. 90% of developers agreed that complete, clear, up-to-date and well-organized documentation is an effective way to learn. When the documentation can't answer a question, new hires get frustrated.
  • Tasks from simple to complex. The study describes three strategies for assigning work to new hires: gradually increasing difficulty, following backlog priority, or handing out loosely defined exploratory tasks. 86.1% of managers use the "simple to complex" strategy for juniors, compared with 48.6% for seniors. A typical first week: small bugs or configuration changes so the new hire gets to know the development process.

Microsoft study: 14 of 18 new hires value their mentor, 90% of developers see up-to-date docs as effective, 86.1% of managers onboard juniors from simple tasks

Why does a simple first task matter so much? According to the same study, finishing a task builds confidence: new developers prove they can deliver value for the team. So don't plan a refactoring of the core for day one; plan a small, clearly specified change that goes through the whole process all the way to production.

Remote onboarding: turn your cameras on

A second Microsoft study (Paige Rodeghero, Thomas Zimmermann, Brian Houck and Denae Ford) surveyed 267 developers who joined the company during the pandemic. Most of them onboarded remotely and never met their teammates in person. Building a strong social connection with the team turned out to be one of the biggest challenges.

The authors derived recommendations that apply to any team with remote people:

  • promote communication and asking for help,
  • encourage the team to turn cameras on in meetings,
  • schedule regular 1:1 meetings,
  • assign both an onboarding buddy and a technical mentor,
  • support different onboarding speeds,
  • assign a simple first task,
  • keep the documentation up to date.

How to plan the first month

GitLab's public handbook has a well-documented example of how to run a buddy system. The buddy schedules an initial call with the new team member, reviews their onboarding progress, suggests useful handbook pages and connects them with subject matter experts. Beyond the initial call, the buddy should schedule at least two follow-up calls in the first week and at least one more for the rest of the first month. Combined with the findings above, that gives a simple plan:

A new developer's first-month plan: a buddy and a mentor, a simple first task, gradually harder tasks and regular 1:1s

Before day one: prepare access, the computer and the development environment. The first day shouldn't be spent waiting for passwords.

Week 1: a buddy and a technical mentor, the initial call and at least two more. The first task is small and clearly specified, ideally a bug or a configuration change, and goes through the whole process: branch, tests, code review, merge.

Weeks 2–4: gradually more complex tasks, regular 1:1s with the manager, another call with the buddy. The new hire should get to know all the important parts of the system step by step.

Throughout: treat every question the documentation didn't answer as a bug in the documentation and fix it. After a few new hires you'll have documentation that really helps.

Five tips for the head of a software company

  1. Onboarding is a project, not improvisation. Keep a written first-month plan and just adapt it for each new hire.
  2. The buddy needs time for the new hire. Count it in the sprint capacity, otherwise helping is the first thing to go.
  3. Prepare starter tasks in advance. Keep a few small, well-described tasks with acceptance criteria in the backlog that are suitable for ramping up.
  4. Don't compare new hires by individual output. Google points out that productivity metrics are highly noisy at the individual level. They are useful for evaluating an onboarding program across a cohort, not for judging one person.
  5. The team owns the documentation, not the new hire. New hires see best what's missing, but fixing it should be the team's normal work.

How mcptask.online helps

Most of the tips above depend on how well your work is specified. In mcptask.online a project breaks down into Epic → Story → Task, so a new hire sees where their task fits. Tasks have priorities and scrum points that automatically turn into an hour estimate, which makes it easy to pick small starter tasks. Dependencies are real blocker links, not a sentence in the description: a blocked task drops out of the next-task queue, so a new hire doesn't start work that can't be finished yet. Time is logged straight to tasks, including from commits, and a JSON, CSV or PDF timesheet shows where the new hire spends the most time and where the documentation left them guessing. Tasks from Jira or Trello come over by import, including hierarchy and history.

The same principles apply to a different kind of new colleague: an autonomous AI developer (the runner) takes tasks from the same queue. A clear specification with acceptance criteria and small tasks help it just as they help a person.

Want specs, estimates and new hires' hours in one place? Register at mcptask.online – the first 30 days are free, no credit card required.

Sources