How to onboard a new programmer on the team?

Two people working together on one computer
Photo by Alvaro Reyes on Unsplash

Today, every company is hiring.

What does happen when the new joiner shows up to work? Is the team ready to teach them about the project? What can we do to make it easier?

The worst onboarding strategy

Before we start talking about doing the onboarding in the right way, let's talk about a terrible onboarding strategy. Why do we do it? To articulate what we need to avoid at all costs.

What can we do to make the onboarding as painful as possible? How can we be sure that the new person won't get productive for the next six months?

It's pretty simple. We don't need anything. All we do is tell people where is the code they will be working on. That's all. The entire onboarding is a link to the repository.

Does it even happen? Of course, it does! I was "onboarded" like this three times.

Let's not do it ever again. We can't send people a link to a vast repository and expect they will read the entire code, understand why you build the application, and how it integrates with other systems. Also, it is dangerous. The new joiner wants to run the code. Can they do it safely?

I won't tell you how long the onboarding should be, but I can tell you what I would like to see. You can figure out on your own how much time you need to discuss all topics with the new team member.

Why are we working on this?

First, I would like to know why we are coding this application. Tell me what it does for the business, who uses it, and what impact it makes on their work. If you can, show me how it works in production.

How does it work?

When I already know why we are working on this project, it would be great to see how it works. Could you show me data flow diagrams or code interactions for the most critical use cases?

Of course, you don't keep them updated all the time. You don't have to. It's ok to update the diagrams every two months as long as someone can describe the differences between the chart and the real world. Maybe you can edit them while talking about those differences. What do you think?

Don't overwhelm the new person with details or exceptions to the general business rules. They won't remember them anyway. Joining a new company is quite a mentally intensive time, so don't expect they will remember every detail after seeing it for three seconds.

What about testing?

In the end, you should mention the tests. How do you test the project? Are there any interesting test cases? Mainly, I would like to see the use cases added after discovering a bug. Those tests usually tell a lot about the project.

First of all, if there are no such test cases, it would tell me the team doesn't care about quality, and I have made a poor career choice.

Second, it shows which parts of the system are problematic. Any external dependencies that keep acting up and that we must patch in our code because the vendor doesn't update them anymore? Is there a part of the code particularly susceptible to concurrency issues?

How to build it?

The new team member is here to make changes to the code. They would love to see those changes in production. What must happen to deploy them?

Imagine that I have pushed my code change to the main branch. What happens next? Where do the tests run? How can I see the results? Where is the build script? How does the deployment happen? Are there any manual steps? (God forbid) How can I run it in a test environment? Can I run it locally?

Are there any rules regarding deployment? No deploy Fridays? No deploy November, December, and January? What else? Are those rules automated?

Last but not least, how can I revert a change made in production. Mistakes happen. At some point, the new hire will need to revert a deployment. You don't want them to look for the documentation in panic when something is wrong.

How do you work?

How do you know what needs to be done? Where do the requirements come from? How can I ask questions about those requirements? How do you document them?

What does the development process look like? Could you walk me through your issue tracking tool and describe what is supposed to happen at every stage? When is a task done? Is there a formal approval process?

How should I describe a pull request? Do you have any coding/formatting standards? Is there a tool verifying those rules?

Also, what do the other team members know? Whom should I ask for help when I have a problem with a database? Who can help me with the build server?

Make them work

Let the new joiner code something. Find a few tasks in the backlog that don't require much effort but require working with different parts of the codebase. Talk them through. Show the new person what needs to be changed and why. Schedule a pair programming session with them, but let them play with the code alone before pair programming.

Also, it would be great if every team member pair programmed with the new joiner at least once during the onboarding. It doesn't matter if the team practices pair programming daily. Onboarding is not about coding. It is time to learn about the project and get to know the people.

Does it look like a lot of effort? Yes, it is a lot. But onboarding is your only chance to ensure that the new person feels welcomed, doesn't break anything, and starts being productive quickly.