When you’ve been involved with a system for a long time it’s hard to remember what it’s like to be new. When you started the system was much smaller and you’ve understood how it’s grown over time. Someone new only sees the current system which is now much more complicated than when you came on board.

An experienced person should be able to understand the code but it will still take them a long time to build up the domain knowledge specific to your codebase if they’ve not worked in that domain before. A beginner has a harder job as they have to work out both which is why they should start with small problem domains.

In software, especially in complex systems, it’s easy to forget that someone new to the codebase hasn’t yet built the mental map of how everything fits together and works. You can tell them when they onboard, but it’s likely there’s so much going on that they’re not going to remember everything. It’s better to pair them with some who joined a little bit before them. That person is going to remember what they found hard to understand and how they figured it out and be able to explain it in detail.

What was the difference in experience levels between the last person you onboarded and the person you paired them with? When was the last time you tried to put yourself in the shoes of a new joiner and thought about what they might need to know?