Here’s how you should onboard new developers

9 min readDec 26, 2017


“You’ve completely f*cked everything up. Leave and never come back.” Imagine hearing that from your manager on your first day at a new job, before you’ve even had a chance to finish the standard onboarding process.

That’s exactly what happened to one junior software developer, who inadvertently cleared the production database after following the onboarding document to set up his local development environment.

U/cscareerthrowaway567 has since shared his story on Reddit and, rightfully so, received a great deal of support and assurances that this catastrophe was not his fault.

Let’s be real, if a manager is shouting profanities at a new employee on their first day or a new developer has the ability to wreak such havoc on the company’s database — it’s not their fault. It’s yours…or more accurately, a fundamental failure of your onboarding process.

While we don’t know which organization u/csscareerthrowaway567 was unceremoniously dismissed from, we do know that such mishaps are not limited to nameless companies. Similar incidents have occurred with Amazon’s Elastic Load Balancing Service, and more recently GitLab, which suffered a loss of production data and hours of service outage.

From the codebase to code standards, team workflows to team culture, there is a lot to bring your new developer up to speed on when welcoming them to the team. By adopting strong onboarding practices, not only can you avoid the disasters mentioned above, you can also integrate your new developer as a fully competent, productive, and satisfied team member.

To help you achieve this, we’ll dissect the best practices for onboarding a new developer from 7 aspects: Hiring, Documentation, Mentorship, Communication, Culture, Evaluation, and Integrating Remote Developers.


Get the hiring wrong and your onboarding won’t matter much.

When hiring a candidate, you’ll want to review their portfolio, past work, and any open source projects they have contributed to on repositories like GitHub or SourceForge. This will give you a better idea of their technical skills and the types of projects they are interested in.

Don’t underestimate interest. Finding a developer who is genuinely passionate about your use-case, business model, and technology is what will fuel and sustain their motivation.

We’ve talked to founders of startups with distributed teams, and one thing all of them have emphasized is the importance of passion.

Zapier’s CTO, Brian Helmig, told us that he prioritizes passion and knowledge when interviewing a prospective team member. Helmig loves to find people that already use Zapier and are excited to bring their expertise to the product.

Hotjar CTO, David Darmanin, also looks for passion and potential over experience — someone who has demonstrated a growth mindset in their career and is ‘hungry’ to expand their skill toolbox.

Someone who has done it all, achieved everything — I don’t want to assume — but they’re probably going to be a little less hungry than someone who is still growing and coming up in their career.

Depending on the size of your team, it might be a good idea to include project managers and internal employees in hiring decisions. This will boost team spirit and pave the way for successful onboarding. Transparency in the hiring process helps neutralize the anxiety current employees may have regarding bringing on new talent, who can sometimes be seen as a threat. Also, allowing team members to meet before onboarding helps build the network that will help the new hire become a fully integrated team member

For more tips on hiring, you can also read: The Ultimate Guide for Hiring Freelance Developers. If you need someone to help you find an on-site developer, Staffing Agency Alternatives to Robert Half Technology may be able to give you some leads.


Documentation will be of paramount importance when onboarding a new developer, especially one working remotely. In our chat with Zapier’s CTO, he drove this point home saying, “information should dispense automatically by design, when it’s needed.

To provide team members with the information they need to do their jobs effectively, you should document everything. From tool guides, organizational charts, workplace setup, SOPs, contact lists, to software tutorials, common bugs, and anything that requires step-by-step instructions.

All of this information should be available in a centralized place, an internal wiki page, for example. A welcome handbook or tutorial would also be helpful in streamlining the onboarding process. While this would require a significant amount of planning and time investment in the initial stage, once set up, the minimum upkeep required would enhance the lasting value.

It’s a whole other realm when it comes to developer specific documentation. Teams should integrate the new developer into the standardized local development environment and workflow framework as soon as possible. The framework should be chosen based on the team’s projects and programming process, GitFlow, Feature Branch Workflow, and Trunk-Based Development are popular options.

Repository documentation should not be overlooked. This should include a wiki detailing how the codebase is designed and how to use it, manifestos on core principles, and any other long-form content pertinent to the project. Don’t forget a README, which should be a quick introduction to the project.


Mentorship can be an invaluable aspect in both the onboarding process and team building. Like all other aspects of the onboarding process, mentorship needs to be thought-out and executed with care.

From day one, or even earlier, there should be a designated person the new developer can reach out to. This team member should introduce the team, be able to answer any technical questions, and walk them through initial projects.

Don’t make the mistake of always assigning mentor duty to your most senior developer. They are likely to eventually burn out, resent the additional burden AND the new team member. In fact, having a junior developer take on the responsibility is a great way for them to put their knowledge to practice, give them leadership opportunities, and quietly check that they are up to snuff.

Here at Codementor, our dev team transitions new programmers into the development workflow by quickly assigning an easy task, like rebuilding dashboards or updating a new feature, to complete using GitFlow practices. This helps the new dev gain a sense of achievement by contributing to production while learning the workflow. While it’s not uncommon for tasks to be defined as they are being build, this should be avoided when assigning introductory tasks to new developers. Initial tasks should be well defined and have clear scope to avoid confusion and frustration.

Here are some tips for mentors-to-be:

  • Get started early with planning, documentation, and SOPs (like code reviews)
  • Don’t solve their problems — help them figure it out by themselves
  • Give and receive feedback
  • Help them learn from their mistakes
  • Do regular pair coding exercises
  • Encourage independent learning with recommended reading like The Pragmatic Programmer


Even before work begins, you should include your new team member in communications: email chains, Slack channels, weekly updates, etc. Don’t dump it all on them at once, ease them in one channel at a time.

Have regular updates when the developer joins the team. Be prepared to answer their questions and address their concerns. This can be addressed in regular stand-up meetings. Ideally, your stand-up meetings should be followed up with written notes that everyone has access to.

Regular one-on-one meetings to check-in on new hires are also recommended. You’ll be able to know how your new team member is settling in and give them any feedback during one-on-one meetings. It’s also a chance for you to listen to them. Managers should encourage new engineers to give honest feedback, share what they have enjoyed, and anything they may be struggling with.


Having standardized communication structures and clear performance expectations are important to onboarding, but integrating a new developer into your company culture will add a shot of stay-power. Team building activities is a great way to way to help your new developer bond with the team while encouraging creativity and spontaneity.

For example, Zapier randomly pairs up team members for a 10–15 minute chat, focusing on personal or professional sharing. Teammates can get to know each other better with the end goal of building stronger relationships.

Other distributed teams often host virtual beer meetings, where everyone grabs a drink of their choice and just chat about random or designated topics. It may sound strange, but it’s a way to bring online relationships to life.

Don’t forget to host regular ceremonies as well. Ceremonies can include demos of soon-to-ship features, buddy coding day, hack day, or whatever you’ve got up your sleeve. These ceremonies should be scheduled so everyone, including remote members, can join. These events are an opportunity for everyone to share their talents and recent learnings, and hopefully, becomes something your team looks forward to.

If you’re interested in how hack days work, check out what Codementor’s dev team produced for our last Hack Day!

A balanced combination of ceremonies and team building will help enhance personal relationships and team spirit. This is a vital part of helping new developers fit into your team culture, which will likely be the most important factor in if your new hire becomes a long-term team member.


One of the best ways to evaluate the performance of new developers is to work on public platforms, like Bitbucket or GitHub where everyone has access to the repository, can see what changes were made, and see what pull requests have been submitted. Non-coding tasks should be done in shared spaces like Google Docs, and updates made on project management tools like Asana or Trello.

Tasks should not be evaluated on the time spent, but the value produced. Constantly looking over your developer’s shoulder is a waste of time and effort. Instead, keep track of their tasks and create an environment for them to produce valuable results by sticking to clean code standards, code coverage expectations, and time-boxed sprints. Use a code review process to make sure new team members are meeting code standards and offer suggestions on where they can improve. Additionally, have regular discussions on current workflow processes and address any barriers.

Lastly, measure by quality, not quantity. Remember, 1,000 lines of messy code will never be as good as 100 lines of clean code.

Integrating Remote Developers

You should include remote developers as if they were actually on-site.

Team introductions and mentoring schemes should still take place when onboarding remote developers. This and the rest of the onboarding process can be done online, through video chat and virtual office tools.

It’s important to help remote developers develop a sense of purpose and camaraderie. Not only will they likely be more loyal and motivated, they’ll also work more conscientiously and overall, have stronger performance.


Don’t expect perfect performance from a new developer in their first couple of weeks. The average employee takes upwards of six months to become fully competent in their role. However, this period can be reduced with proper onboarding.

To optimize your company’s onboarding process, you can start by asking yourself a series of questions:

  • What does my developer need before they start?
  • What information, hardware, software, etc. do I need to provide prior to day one?
  • What are the biggest time consumers with new hires?
  • What are the most frequent mistakes made by, or in connection with, new hires?

If you can answer these questions and address them in your onboarding procedure, you’re on your way to successfully integrating a new team member. There will be no need for profanity or data loss, which we’re pretty sure isn’t part of your company culture.

Happy Onboarding!

Originally published at