Engineer onboarding done right should get your new hires to solve issues and merge pull requests at a rapid pace. Team leads often miss the opportunity to pivot retention and witness their engineers fail to thrive while focusing on all the wrong things.

Onboarding, a predictor variable if you will, of an employee’s success and time-to-value for the company poses its own unique set of challenges with software engineers. When done remotely, onboarding can take the challenge to an entirely new level.

In the past few weeks we made substantial additions to our engineering team, and here are some of our pivotal takeaways from the [remote] process.


  • How to set up for success giving your codebase the right context
  • Learning by doing: a laser-focused streamlined set of coding tasks (explained in detail below)
  • Collecting feedback, applying and optimising

Basics: installations for success

The technical secret sauce to engineer onboarding is described in the next section, but to set things up for success, we need to get the basics right (we’re not talking about fancy desk arrangements and busy mentors). Companies with outstanding onboarding programs, make sure that new hires can address their new role with confidence from the get-go. For many engineers, setting up their development environment is the key to getting started, as well as getting product and business context.

What we did:

  1. Intro’s and installations. We created a list of installations and shared it with our new hires in advance, followed by a designated session with an experienced team member that made sure their dev environment was up and running on their first day. Note, independent installations can help new hires better understand their dev environment, also pushing us to strive for an elegant system that is quick and simple to set up.
  2. Code in context. We made sure the first day included an introductory session with the entire team and provided an overview of the company and business. To give our codebase and development processes context, we provided an overview of our product evolution over Zoom and recorded the session for future onboardees, discussing various iterations and hypotheses already tested and the product at present.
  3. User-oriented. Early in the process, we made sure our new hires are users of our product, so they could understand the user experience first hand.


  • Minimize the time your senior team members spend onboarding new hires. Aim to onboard a few engineers on the same day and hold joint sessions. One of our hires also mentioned that

“it felt great to be able to do most of the training independently without having to ask questions about trivial parts in the code.”

  • Describe how their first day is going to look like and share a list of installations, with a document describing known issues and common pitfalls with setting up the environment. List the mentors, time frames, people to meet, and documents to read. Your first day should include: intro session with the entire team and provide an overview of the company, and the product (context).
  • Ask the new engineers to take notes while installing their environment, and consequently update the installation guide for future engineers. This gives the new engineers an opportunity to contribute from the get-go.
  • Record your onboarding sessions for future remote onboardees. Make sure you have a knowledge center to keep these on file, and your documentation set up and easily accessible.
swimm developers working on backend

Method: learning by doing [done right]

The next challenge was learning by doing, and successfully getting our engineers oriented with the team’s codebase.

Our hands-on code exploration methodology is simple. We generate from our codebase, tasks that highlight the most relevant parts of the code while providing automated hints and tips. We focused our learning process on one element at a time. For example, we generated a bug in our codebase and then the onboardee’s task was to fix that bug. Examples from our codebase below highlight the CLI (which is just one element of our product). After solving these tasks, we provided our hires with tasks that rely on CLI-specific knowledge, and their code was then pushed to production.

  1. Start small. To familiarize themselves with our codebase our engineers were assigned laser-focused learning tasks starting simply with how to pass parameters to an existing command. In the first task, we focused on a command called swimm reset (that resets the internal program’s state). When the users run this command, they are prompted: “Are you sure?”, and only upon answering “Yes”, the reset takes place. The first task was to add the option —- quiet, which results in performing the reset without prompting the user for confirmation.
  2. Guided success. The second task asked the engineer to add a new command to the CLI. The third task was more complicated and involved understanding the entire flow of our CLI well. In order to solve it, the engineer had to understand a few different commands and how they integrate. Within these independent exercises, our new hires got a lot of automated guidance and hints if they were stuck, and got to compare their solution with the one originally implemented in the codebase.
  3. Touch base. We made sure to have a daily session with the team and allow the new hires to ask questions. This doesn’t mean they couldn’t ask questions during the day, but it assured us that at least once a day we touch base. After a few days, we asked our new engineers what they felt was missing in their initial process.


  • Create a streamlined set of tasks that covers all important aspects of the codebase.
  • Share knowledge across team members by providing focused hands-on tasks.
  • Optimize your set of tasks over time, and ask your new onboardees to contribute.

Code review: lessons learned

To sum-up, after only a few hours, our new engineers managed to implement a CLI command from scratch and tackled their first issues with confidence and a clear understanding of the main parts of the codebase. Within a few days, they felt confident in the parts of the code their onboarding plan covered and were able to tackle tasks with ease and contribute to each other’s onboarding plans.

Main takeaways :

  • Start with feedback. After just one day, we asked the onboardees to provide some feedback and we improved the process consequently. Specifically, we let them update the instructions for setting up the dev environment following their experience.
  • Plan meticulously. Onboarding remotely means having clear agendas planned in advance, holding a very organized first day with a list of important sessions. For us, it was critical to create a streamlined set of tasks, one that evolves over time and is always relevant and updated for a new engineer. We also found out that onboarding processes have a tendency to spark new conversations and ideas and used the momentum for knowledge sharing.
  • Apart but together in the process. Although onboarding remotely, it’s important to engage new hires and make them feel part of the team. Finally, ask your new engineers what they feel was missing in their onboarding process. We found that even creating a single task that covers one complex issue, can save valuable time and confusion from future engineers.

*Disclosure: We recently hired new engineers to Swimm, and invited them to use the Swimm app to orient themselves with the new code. Since Swimm is a tool helping engineers contribute to any codebase faster and better with automatically generated hints and codebase insight, we were putting our own work to the test. It was a unique introspective process. We are happy to share our learnings.*

To learn more about Swimm, sign up for a 1:1 Swimm demo