Adding a new engineer to an existing project might be quite challenging and time-consuming. But what if we could completely standardize the onboarding process?
Onboarding is a term that has multiple meanings in the software industry: it can mean introducing someone new to colleagues and company culture, a new client can be onboarded to a product, or we can use the term in the context of adding a new engineer to an existing project.
All of the processes described above are challenging and take a significant amount of time and energy from both parties — from the one who is onboarding and the one who is trying to get on board.
How do we know that we are ready for a new team member?
Usually, we start thinking about onboarding engineers to the team when we need additional manpower due to a larger amount of work. If we plan ahead, we will be able to predict when extra help will be needed; however, in some cases, it happens that we need to add additional engineers basically overnight. The reason for this can be an additional feature, sick leave, a shorter deadline, or something similar.
If the team is not prepared for rapid onboarding and handovers, someone will likely feel pressured and stressed.
To be prepared for situations like this, we need to ask ourselves:
- What is the scope of knowledge that this person needs for his work?
- Where can he find information about domain knowledge?
- Which tools does he need?
- In which communication channels do we need to add him?
- Access to which services will he need?
- How will he set up the development environment?
- Are our ticket descriptions descriptive enough?
We should not underestimate these questions because we might ruin the engineer’s experience and kill the enthusiasm of a newcomer even before he starts working on a project.
If you have answers to the above questions documented somewhere, you are on the right track.
Can we completely standardize the onboarding process?
As a engineer, you can deal with multiple different projects with different complexity, team size, and time constraints for delivering a feature. That’s why it is hard to say that only one onboarding approach is correct and others are entirely wrong.
Each team needs to find a way that suits it the most, but all can follow some general guidelines and good practices.
In a perfect world, we would have enough resources and time to onboard a new engineer—meaning, a new team member gets a dedicated person who presents a project, codebase, architecture, CI/CD flows, project rituals, helps set up a local environment and is available to answer all project- or task-related questions.
However, in many cases, the lead engineer, who has the most overview, knowledge, and usually the most responsibilities, also takes charge of onboarding.
In smaller teams, where there are not a lot of resources, onboarding might cause a loss of productivity, a deployment delay, and higher pressure for the engineer performing the onboarding. Under the assumption that a smaller team works on a less complex project, which is not always the case, it might take a day or two before a new engineer is ready for his first task.
On the other hand, we can have bigger teams with more complex projects, where the onboarding process might take a week or even more. This can have a significant impact on the project and the team.
From a learning perspective …
Let's look at the example where a team grew from 3 to 8 engineers in less than two months. We worked on a complex project with multiple services, databases, and consumers.
It took at least two full working days to get the new engineer up to speed on the architecture, the relationship between services, team rituals, giving credentials, setting up the local environment, explaining some domain-specific topics, etc. We all agree that this is a lot of information for a newcomer in the first couple of days.
When onboarding happened in the middle of the sprint and release was near, we, unfortunately, forgot to explain some things or give certain access. On the other hand, we duplicated basic information that didn't need to be done twice because multiple engineers working on onboarding weren't in sync. There’s no harm in hearing some things twice; however, if you are listening to the general overview for the third time, it is not always beneficial and takes up unnecessary time.
This project was the turning point where we started to think about how to improve the onboarding process to make sure we gave all the needed information and didn't forget anything important.
... to an improved process
During our review, we found that the onboarding process could be improved so that all the needed information is given and no important details are left out.
We found that the agenda for the onboarding meetings was similar in most cases. This gave us the idea of creating an onboarding checklist - similar to what pilots use to check the plane before takeoff.
At least we won’t have casualties if we forget something, or will we?
At the end of the day, we don’t want a newcomer to lose enthusiasm because they didn’t get enough information about the project, got stuck setting up the environment, didn’t have access to the code repository, or something similar.
Example of an onboarding checklist:
The checklist was not enough …
Alright, we had a checklist as a guide, but we still spent two days onboarding a new engineer. What can we do there?
The first thing is to prepare general and technical documentation about the project and give it to a new team member as a reference, even before the first onboarding session, so that he might already have some questions prepared for the first meeting. Information can be written in any format, but it needs to use a simple, not domain-specific, vocabulary. It should also include external links to additional resources, diagrams, and code examples if needed.
It’s especially important that you have good documentation on how to set up a local development environment and run the project because we all want to do some coding as soon as possible.
It would help if you also found out which processes take the most energy to explain and hand over. It’s best to write them down as a step-by-step tutorial so you don’t have to repeat them each time. New engineers will remember more if they read and try things out themselves. Moreover, they might tackle some technical difficulties and will be challenged immediately. However, ensure that you have some common issues described in a tutorial, which might save everyone plenty of time. You can also use them to update the documentation and tutorials when they run into new problems that haven't been covered yet.
Is our onboarding process perfect?
I would be overjoyed if I could say that we have a flawless onboarding process, that all newcomers receive all the information they require right away, and that everything runs smoothly.
We are still learning and improving the process, but the steps described above have made our lives easier.
