Improving Developer Onboarding: Best Practices

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.

Consider this: A 2022 survey revealed some sobering statistics. 52% of new hires in the United States contemplate resigning within the first three months of starting a new position, and a staggering 74% actively look for new opportunities before their first anniversary. These numbers underscore the critical importance of a well-executed onboarding process, especially in an industry where talent is both in high demand and in short supply.

Let’s delve into the best strategies that can transform a potentially overwhelming transition into a seamless and productive journey.

Onboarding Approach - “Sink or swim” or “Here are 80 hours of lectures”

Does this approach sound familiar?

“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 videos 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.

Therefore, 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.

This, however, might result in situations like this:

“We’ve scheduled for you daily 8-hour video conferences where the engineering team will walk you through all of their code, line-by-line, for 4 weeks. Then you can start working on the code - if you need help we have documentation throughout 3 different systems, although some might be incomplete, contradictory, or outdated.”

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.

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. Unfortunately, this can often turn into:

“We’ll wait for the engineers to arrive and they’ll figure something out together”

In practice, the best onboarding approach may involve a combination of these 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.

Onboarding Best Practices - The Big Picture

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”:

• COMPANY → How does their role fit into the big picture? Engineers don’t just write code, but create products, services, and experiences. For example, can they see how the feature they’re working on will help drive the business results the company is pursuing?
  
  Having exposure to executive leadership and high-level strategy also allows new hires a glimpse of the company culture and a better understanding of business priorities.
• PRODUCT → What kinds of experiences are the typical customers having? Engineers that try the product first hand have a better understanding of user pain points, can analyze requirements, flesh out features, and implement designs that consider future functionality.
  
  Including product recordings or customer interviews in the onboarding, and scheduling meetings with Support, Sales, Customer Success, and Marketing also provides insight into the user experience.
• ROLE → Ahead of time, the hiring manager, should have fleshed out a document explaining the job-specific tasks, day-to-day responsibilities, and milestones. One of the first steps in the onboarding process should be walking through this together to clarify what’s expected of the role and any specific projects or tasks they will be working on.

Laying the ground work

In the initial stages of a developer's journey, laying the groundwork is paramount. It encompasses setting up the right environment, gaining a comprehensive technical overview, immersing oneself in the team's domain, and getting to know the company’s interpersonal dynamics through an onboarding buddy, all of which are essential elements for a successful onboarding experience.

ENVIRONMENT SETUP

Ideally, all the equipment for a new engineer should be prepped and ready to go: when they receive their laptop, all they would need to do is log on and change the password. However, this may not always be possible (especially for a startup).

If you can’t pre-install all the necessary programs, libraries, firewall policies, etc. you should at least prepare the following in advance:

1. The correct permissions and credentials so that the engineer can access:

• Development, testing, staging, and production environments.
• Source code, version control repositories, databases, cloud services, etc.

2. Team communication and collaboration tools (e.g. Slack, email & calendar lists, project management software, etc.)

An “Environment Setup Guide” with step-by-step instructions (ideally standardized for the entire team) for setting up the development environment, including installing the necessary software, configuring IDEs, setting up version control, and connecting to relevant databases or services.

TECHNICAL OVERVIEW

New developers can be very eager to understand the code and start contributing right away. However, this is the ideal opportunity to invest time in learning the high-level system architecture and working piece by piece toward understanding the details of each component and the technology used.

By walking through an interactive diagram of your distributed system architecture, you can highlight how all the moving parts work together: clients, servers, databases, third-party systems, dependencies, etc. This can also be an opportunity to explain why the systems are designed the way they are and the guiding philosophies of the team (i.e. how you make technical decisions).

Afterward, it can be helpful to do a high-level, unstructured review of the existing codebase and various knowledge base repositories, where historical decisions, best practices, and lessons learned are documented.

*Ideally, all the technical documentation is colocated in a single, easy-to-navigate location and it’s always up-to-date. Multiplayer can do that!

TEAM & DOMAIN ORIENTATION

Besides holding 1:1 and team meetings to introduce the new hire and discuss the team's current projects, priorities, and upcoming initiatives, it’s also important to:

• Define the domain of the team: its purpose, function, brief history, etc.
• Introduce the team dynamics and communication channels (e.g. how the team works together and with other teams or departments, what code of conduct and ethics the developer should adhere to, etc.)
• Introduce the software development methodology, testing approach, branching strategy, error handling strategies, coding standards, programming process, etc.

ONBOARDING BUDDY

The onboarding buddy should ideally be someone from the engineer's new team who is working in the same domain and knows all the processes, pitfalls, and gotchas. They have already written, reviewed, and merged code into production and they will show the new engineer how to do it with the same approach.

Most importantly, though, they will be their guide to understanding all the inter-team and interpersonal connections within the organization.

In fact, apart from learning the technology, the hardest part of joining a new company is meeting people and getting to know who owns which domain and who the right people to ask questions are.

Building Smart Habits

As the onboarding journey progresses beyond the initial stages, the focus shifts towards building smart habits that foster collaboration, skill development, and continuous growth. This phase encompasses the adoption of pair programming practices, committing their first PR, and embracing a mindset of ongoing learning, setting the foundation for a developer's long-term success within the team and organization.

PAIR PROGRAMMING

Pair programming sessions are a great way to familiarize your new hire with the overall codebase and coding standards. It’s a practice that has long-term benefits:

• It’s a bridge to meaningful relationships - newcomers paired with mentors learn faster and build connections that drive collaboration.
• It ensures team redundancy and knowledge sharing - at least two people are always familiar with different aspects of its system.
• It results in a higher quality of code - the feedback loop is immediate instead of having to wait for pull requests.

It’s important to note that this is a collaborative exercise and not just a “watch me code” session. Passive shadowing should be alternated with hands-on practice in learning the codebase, development environment, and systems architecture, which is invaluable to building confidence in a safe environment.

CODING

To start, new engineers should be assigned 3-5 small, non-critical tasks that touch different areas of the code base — for example simple "technical debt" tasks, well-contained features, bug fixes, and test coverage. Alternatively, they could tackle sandbox projects where they can experiment, fail, and learn without fear.

The objective is to facilitate the developer’s ramp-up with real, but manageable, work so that we can nurture their confidence, and sense of achievement for contributing meaningfully to the team.

ONGOING LEARNING

In tech, the journey of learning never ends. Your company should encourage you to dedicate time to online courses, workshops, and challenges… or just to reading manuals!

Drive collaboration from the start

As the previous paragraph shows, there’s so much more to onboarding than simply mastering the tech stack. Being productive also encompasses feeling valued and secure in asking questions, having all the resources you need to fully understand your team's domain, and being able to effectively collaborate with your new colleagues.

Driving collaboration from the start becomes even more critical now that most engineering teams are distributed teams. While the COVID pandemic certainly accelerated the global distribution of the workforce, the decentralization of teams is a trend that developed in parallel with the rise of global, highly-available modern software systems. It’s also a trend that doesn’t show signs of decelerating, despite all the recent RTO (return to the office) policies: a 2023 Gallup study found that 71% of US employees would prefer a hybrid or remote job.

Effective onboarding of a new member to a distributed team necessitates a deliberate focus on fostering connections, building trust, and ensuring effective communication channels and tools.

Onboarding new developers is a complex process and success is a team sport. To empower your team, choose the right tools for visual collaboration, and for establishing communication best practices.

Multiplayer allows you to visualize, design, and develop your distributed software with a visual and collaborative tool. All the information you need to onboard a new developer — system architecture overview, codebase documentation, API documentation — is at your fingertips in an easy-to-navigate, always up-to-date repository. Sign up for free to see for yourself! 😉