[Part 2] Developer onboarding: best practices

When a new person joins your team, everything comes at them all at once: new projects, processes, tools, technologies, and codebase. 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

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.

If you can't pre-install all the necessary programs, libraries, firewall policies, etc. (which might be the likely scenario for a startup), 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.
• Observability and debugging tools (logging platforms, APM tools, session recording tools, etc.)

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

3. 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.

If your team uses infrastructure-as-code and containerized development environments, this set up might be even more streamlined. Tools like devcontainers, Codespaces, or Gitpod can reduce environment setup from days to minutes, letting new engineers focus on learning the codebase rather than fighting dependency issues.

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.

Learning Through Real User Sessions

Beyond static documentation, one of the most effective ways for new engineers to understand system behavior is through observing real user interactions.

Full stack session recordings provide an invaluable learning tool during onboarding: new developers can watch how users actually navigate the application or record a session replay themselves to see which API calls are triggered by different actions, and observe how data flows through the system in practice.

This approach bridges the gap between theoretical architecture diagrams and real-world system behavior. When a new engineer reviews a session recording of a common workflow, they can see:

• Which frontend components handle which user interactions
• How requests flow through backend services
• What database queries are executed and when
• How the system responds under different conditions

Additionally, reviewing past bug investigations through session recordings serves as practical training. New engineers can see how experienced team members diagnose issues, what they look for first, and how they trace problems across the stack. This "learning by observation" accelerates ramp-up time and builds debugging intuition that would otherwise take months to develop.

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. How the team works together and with other teams or departments, what code of conduct and ethics the developer should adhere to, communication norms for remote/hybrid work, etc.
• Introduce the software development methodology, testing approach, branching strategy, error handling strategies, coding standards, programming process, etc.
• Explain the support and incident response workflow. How bugs are reported, triaged, and resolved; who handles on-call rotations; and what tools the team uses to investigate production issues

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.

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.

Tips for effective buddy pairings:

• Match new engineers with buddies who have 1-3 years of tenure (senior enough to be knowledgeable, recent enough to remember being new)
• Set clear expectations for the buddy role, including time commitment and specific responsibilities
• Schedule regular check-ins between buddy and new hire, but also encourage informal, ad-hoc communication
• In remote environments, consider scheduling virtual co-working sessions where the new hire can shadow their buddy's daily work
• Recognize and reward employees who serve as effective onboarding buddies

The buddy relationship works best when it's bidirectional: encourage new hires to share fresh perspectives and questions that might reveal outdated practices or unclear documentation. Sometimes the "beginner's mind" can spot problems that veterans have learned to work around.

TL;DR - Documents to prepare