[Part 1] Improving your developer onboarding

When a new developer arrives at a company, everything comes at them all at once: new team, projects, processes, tools, technologies, and codebase. It's like stepping into a bustling metropolis with its own language, culture, and way of life.

Onboarding into life in this busy metropolis isn't just a process; it's a pivotal moment. It's the bridge between the excitement of joining a new team and the real, day-to-day challenges of contributing effectively. It can be the catalyst for a developer's success or, unfortunately, the precursor to their departure.

Recent data shows that 52% of new hires contemplate resigning within the first three months of starting a new position, and 74% actively look for new opportunities before their first anniversary. These numbers underscore the critical importance of a well-executed onboarding process. With the rise of remote and hybrid work environments, creating connection and clarity during onboarding has become more challenging, and more crucial, than ever.

In this blog post series we talk about the best strategies that can transform a potentially overwhelming transition into a seamless and productive journey.

(1) Improving your developer onboarding approach
(2) Developer onboarding: best practices
(3) Developer onboarding: smart habits
(4) Developer onboarding: documentation must-haves
(5) Developer onboarding: documentation common mistakes

Strategies that don't work

"Sink or swim"

"Hey, I've sent you an email containing all the materials you will need to get familiar with what we do. You will find 10 hours of recordings that will help you understand the business and around 15 different tools to set up. Any questions? Cool, welcome aboard!"

Some hiring managers believe in the old adage of "sink or swim," throwing the developers into the deep end as soon as possible… and, oftentimes, without much assistance.

While hands-on practice and research are a cornerstone of ramping up your codebase and tech stack knowledge, it may take longer for a new engineer to obtain the critical knowledge that other team members have.

Even if an engineer is used to self-learning and can gradually fill in the "known unknowns" themselves, they have no way of knowing what the "unknown unknowns" are (things they don't even know they are missing), unless someone in the team tells them. For example, the fact that they use an obscure legacy message queue solution, just for a specific feature.

"Here are 20 hours of recordings"

"We've scheduled for you daily 8-hour back-to-back meetings where the engineering team will walk you through all of their code, line-by-line, for 2 weeks. Then you can start working on the code. If you need help check the docs in these 3 different systems, although some might be incomplete and/or outdated."

To help the new hire hit the ground running and provide more comprehensive guidance, the hiring manager might decide to set up a more structured onboarding process. Alas, even the best onboarding plan can't anticipate every question, or expect the new hires to remember everything they've learned in the first week.

"We'll figure things out together"

"We'll wait for the engineers to arrive and they'll figure something out together"

Since the above two strategies are not entirely successful, the hiring manager might think that the best solution is to craft a personalized approach that aligns with the individual developer's role and experience. However, this often results in last-minute, cobbled together resources and meetings that disrupt daily work.

It may also need to wasted time preparing any documentation as, due to their hasty and "customized" preparation, will need to be revised or expanded to fit the next hire's role and scope.

Start with the "big picture"

In practice, the best onboarding approach may involve a combination of the above approaches.

For example, starting with a structured onboarding to cover essential basics and then transitioning to an agile or self-paced approach once the engineer is comfortable, all the while ensuring they have access to thorough and updated documentation.

Regardless of the balance you strike between structure and flexibility, your main objectives should be (a) a great first impression of your team, company, and product and (b) setting up your new hire for long-term success.

The length of onboarding can vary from organization to organization and from role to role. Usually, the minimum is 3 months, but given the huge impact it can have on the new engineers' productivity, morale, and retention, it's a process that can last up to 18 months.

To ensure the new engineer has all the context they need to become a functioning member of the team as soon as possible, we recommend starting with an overview of the "big picture":

Deep dive into the product

Diving into the details of the product, is an aspect of onboarding that is often-overlooked aspect. However it's crucial to help new engineers understand how users actually interact with the product and what happens when things go wrong.

Traditional approaches rely on reading through bug reports, sifting through logs, or having senior engineers explain past incidents. These methods, while valuable, can't fully capture the complexity of real user experiences.

Full stack session recordings have transformed this aspect of onboarding. Instead of trying to piece together the user experience and correlated system behavior from fragmented logs and second-hand descriptions, new engineers can simply replay actual user sessions or record a replay themselves.

Seeing the complete context from frontend interactions through backend API calls and system responses accelerates understanding in several ways:

System architecture understanding → Watching how requests flow through your distributed system provides intuitive insight into system architecture that's hard to gain from documentation alone.

Debugging workflow familiarity → New hires learn the team's actual debugging processes by shadowing how experienced engineers investigate issues using session recordings.

Reduced fear of production → When new engineers can safely observe and replay production issues without risk, they build confidence faster and feel more comfortable contributing to critical systems earlier.

This visibility into real user experiences and debugging workflows helps bridge the gap between theoretical knowledge and practical application, making new engineers productive members of the team more quickly.

TL;DR - Documents to prepare for the "big picture"