Home About Newsletter Twitter RSS

The Ultimate Guide To Onboarding Software Engineers

The Ultimate Guide To Onboarding Software Engineers

March 24, 2022

Table of contents

It’s Monday. You’re back at work after a nice weekend, feeling excited as the new engineer is joining your team today! She arrives, gets her laptop and first coffee, you have a nice chat about the weekend, then the question hits you: “So, what’s my first task?”. You don’t really have an answer to this – it’ll take time for her to be able to actually deliver tasks, there’s so much to learn for that, the stack, coding standards, that quirky legacy codebase, the flaky tests, the deployment system, how you do code reviews, wait, then there’s the release train, too… sigh! It’s fine, you think, she’ll figure it out, right? Right? “Well, wait for the engineers to arrive and they’ll figure something out” – you answer, then you excuse yourself, a meeting is starting in 5 minutes and you need to be there.

A week passes and you have your first check-in with her. She seems… nervous and confused. She doesn’t feel she’s learned much and she feels very insecure. She must be unfit for the role, eventually, as she clearly should be delivering tickets by this time, right? It’s only a matter of time before getting fired during the probation period. These are some of the thoughts going through her mind. Or, if she’s experienced, she might think “What a crap place. It was a mistake signing that contract. Well at least I can leave within 2 weeks”.

This story about onboarding software engineers might sound familiar to you – it is very common, sadly.

If you’re in a bigger or more mature company, there’s a good chance HR figured out at least some of the onboarding. They typically enroll new hires in a training program or orientation to help them get acquainted with the company, its departments, policies, and the basic outline of the position. As important as it is, this doesn’t include engineering onboarding, team-level rules of the game, architecture, coding standards, etc. – that needs to happen within the function.

As an engineering manager, I had messed this up more times than I’m comfortable admitting. I didn’t provide a structure, subject matter, and mental support to new joiners which resulted in a very bumpy ride for some of them. There was one engineer leaving clearly because of this.

Even companies that solved the hiring side of “hypergrowth” get bitten by the lack of proper onboarding.

Candidate experience doesn’t stop at signing the contract.


Why is onboarding hard for both engineers and managers?

It’s a combination of known unknowns and unknown unknowns for the new hire

As a new joiner, it’s tons of learning, and that is never trivial. Just like with most types of learning, there are things you already know in the domain (e.g. you are proficient with a programming language), there are things you know you need to learn yet (e.g. you’ve heard about HTTP/3 but you know nothing about it practically), and then there are things you don’t even know you miss (e.g. the team you just joined uses this weird legacy message queue solution you never heard of).

If you’re structured enough you can gradually learn your known unknowns, but there’s no way to understand what else you need to pick up unless somebody tells you. The problem is, it’s mostly known knowns or known unknowns for the rest of the team, so it might feel ‘trivial’ to them (”well of course we use event sourcing, we’ve always done that!”).

This is one of the reasons why structure helps. If there’s a list or mind map of things to know, one can navigate.

It’s emotional

Being a new joiner is usually a high-stakes situation. You’ve given up a previous, maybe comfortable job, you know you can be let go quickly in your probation period, and there are tons of unknowns in the equation at this moment.

Will you get to stay?

Can you learn all this?

Will you like it here?

Will they like you?

Are you performing well? What is expected of you exactly at this stage?

Then there’s “onboarding fatigue” – the feeling that all you do is learn things. This can be especially bad if you’re coming from a job where you performed really well – the gap is just too great.

As a manager or an onboarding buddy, you can help tremendously by setting clear (and realistic!) expectations and being moral support. Telling the new joiner repeatedly “you can do it”, “take your time”, “we’ve all been there” might sound like nothing to you, but might mean peace of mind to them.

It’s expectation management

There are multiple stakeholders in this situation. The rest of the company might expect you to deliver the new shiny project fast. Your PM might expect the team to move faster since you just got a new engineer. Your other engineers might feel the new team member is slowing them down.

You need to acknowledge one important fact and align on this with your stakeholders: a new hire will cause the team to take a velocity dip before getting faster. Onboarding takes time and effort. It’s an investment. Ideally, you know all this way before the new joiner arrives. Ideally, you agreed on all this when you decided to hire. Ideally, you don’t even need to tell this to them as it’s part of your culture. If not, it’s never too late to have these talks.

In a later section of this post, I’ll show you a simple 30-60-90-150 day framework for this.


Onboarding happens on multiple levels and in multiple areas

Finding your way around in onboarding-land is not easy

Onboarding is not a single thing. It happens in multiple parallel tracks which require different strategies. This makes onboarding even harder as participants (the new joiner and their manager) need to juggle focus and time invested.

Onboarding in the team

The first and most immediate scope is the team. This context is where work gets done and where most of the time is spent. Onboarding here already happens in multiple areas, for example:

Making connections – getting to know the team members, dynamics, how to talk to whom, who to talk about what, pet peeves, preferences, moods, roles.

All the unwritten rules nobody tells you but you slowly discover

Roles and responsibilities in the team (who does what, what can you expect from certain people). Here, doing an ARCI exercise together with the whole team can be super helpful. Or just walk the new joiner through the one you already documented if it’s up to date.

Workflows and processes, and the way the team does agile(ish).

The team’s role and purpose in the organization and in the product(s).

Learning the ropes of the tech stack(s) involved. There’s a great article called Development cold start which describes the importance of good tech onboarding. Hint: it’s more than documentation, though good documentation is key. Pair programming also helps. So do walkthrough and overview sessions (of architecture, development processes, and codebases) led by experienced engineers already well-versed on the stack.

Learning to work with your manager. Understanding their role (can be quite different from company to company), personality, interactions, and expectations.