Joining a new team is pretty exhilarating: tackling new codebases, learning interdependencies and systems, and collaborating with new teammates to bring different products to life. But the learning curve can be daunting, confusing, and even debilitating, not only undermining developers’ skills and ambitions as new team members, but delaying their ability to contribute to the bigger picture.

We’re taking a deep dive into best practices for onboarding and, as a critical point of entry, we want to know what’s working to get new developers feeling productive, safe, and able to contribute meaningfully and quickly.

How Big Code creates big problems for developer onboarding

With the rise of Big Code—that is, how code is growing in volume, variety, velocity, and value—in all industries, new developers are feeling its influence across the board. In a 2020 survey of software professionals, the top-cited challenge due to the dramatic rise in code complexity was the time and effort for new hires to be productive. But why does the emergence of these sprawling, complex codebases create big problems for new software developers? And what’s a better path forward?

If we think of the era of Big Code in terms of the massive growth in the volume and complexity of code that teams are required to manage in the hyper-specific, and possibly imperfect, systems within any organization, this creates an ad hoc environment for us to navigate—without guidance, standards, and tools to keep things in sync with our new teams and leadership. But every new workplace is different, and code overload can mean different things in different environments. Not only are new team members just trying to understand the code, they’re trying to learn how the company uniquely structures and thinks about its code. Marek Zaluski, a developer education engineer here at Sourcegraph, noted, “The biggest challenges are getting familiar with what’s already there. The bigger it is, the more difficulty there is.” And without effective code search or support, you end up dividing your hours into learning and researching new codebases, and then actually implementing them.

Codebase overwhelm can lead to anxiety and self-doubt

A whopping 94% of survey respondents report that their organization is affected by Big Code, regardless of industry or the number of developers on their team, with a variety of challenges getting new developers up to speed. Almost everyone is now onboarding into a Big Code environment, and under its umbrella falls increasing testing metrics, incident handling, operational monitoring... But the consequences of Big Code on onboarding are two-fold: it requires both technical onboarding, as well as a cultural one. Not only does being thrown in the deep end result in wasted time and productivity, but it also instills anxiety and fear—which cycles back to mistakes, searching code in silo with personally resourced tools, distressed work environments, and piecemeal feedback that doesn’t lead to structural change.

Even when they’re well qualified for the job, new developers will have moments of self-doubt and impostor syndrome. “In the past, I’ve been in situations where I’m thrown into a new project and expected to figure it out. It’s stressful, and the bigger the codebase, the more anxiety I have. It’s hard to even know where to start,” said Marek. Adam Harvey, another developer here at Sourcegraph said, “Culture becomes important. You want the space to make mistakes when you’re coming into a new environment. You want a combination of psychological safety (knowing that your team won’t throw you under the bus) and technical safety (guardrails to know that you won’t make a huge mistake for a customer).” Marek agreed, saying “Part of psychological safety is knowing that asking questions is encouraged. You can start to feel isolated if you’re worried about bothering your fellow engineers by asking questions that seem too simple.”

How engineering managers can implement better onboarding

Repeatable, scalable onboarding that continually raises the curve is an ongoing and collaborative effort. Here's how to go about it:

Get everyone involved

Everyone, not just recruiters and HR, contributes to a great onboarding experience. Adam noted, “The philosophy is that we’re all on one team, which requires buy-in from everyone to put in the time and effort to support each other. Our new hires are told by the CEO that we’ll drop everything to help with any questions they have. This sets a strong signal across the company that it’s not just platitudes, but a priority.” But he added that setting the tone is not enough, and pointed to implementing set meetings to help unblock people, regardless of whether they’re new to the team or just stuck.

Make it safe to ask for help

Our developers say that setting timers for new hires can help: if they aren’t making progress in 15 minutes, encourage them to ask a teammate so they’re not taking a full day trying to figure out how to do something. And that they know this is welcomed and okay. Because we’re fully remote at Sourcegraph, we also employ an onboarding buddy system, pairing people who usually aren’t in the same department, which can help measure how your team dynamic fits into the rest of the company.

Have a single source of truth

Ongoing documentation, shared resources, open access, and keeping everything a new developer needs to know in a single source of truth (such as your company handbook or project management tool) helps address the complexity and volume of your org’s codebases. Having all the information in one place reduces the anxiety of not knowing where to find everything, and lets new developers swiftly learn, communicate, and execute against clear goals.

“Once you’re knowledgeable of a codebase, it’s difficult to put yourself in the shoes of a new developer, knowing where to start, identifying interdependencies, connections and managing libraries,” says Marek. Having a centralized system with clear documentation helps distribute knowledge equally.

Sometimes being lost isn’t just a discovery problem, but a social one. If you asked a group of engineers which databases to use, you might get multiple answers. Clear communication, guidance, and standards builds a transparent and safe environment to know how much knowledge you’re still missing before you can fully participate and contribute. Adam added, “A huge part of onboarding into a Big Code environment is how we interact with each other, and learn how to navigate through systems like operational monitoring, testing, or incident handling with reasonable confidence.

Make sure everyone is using the same resources and tools

Marek stated, “Sometimes when you’re reaching for a particular tool or library, you don’t even know if you have something in-house already or if you need to look externally. Codesearch makes it easier to look through your list of repositories to find what others have done.” Ensuring it’s clear what tools are available and in use helps new developers quickly find their footing, familiarizing themselves with codebases and coding conventions and eliminating the need to start from scratch every time.

Successful onboarding doesn’t just affect the quality of the work, but pushes a company forward by integrating new hires as an essential, valuable part of a team, significantly decreasing the time for new developers to be productive, motivated, and feel fulfilled in their work. Solving for the issues inherent with the emergence of Big Code, together, is a vital part of it.

Curious to learn more about the emergence of Big Code? Read the full report.