In a moment of despair, you turn to a web search and find this article describing your exact situation.
You’re skeptical about finding useful advice – after all, every new colleague is different, and every project has its own quirks. You begin to ask yourself what it truly means to onboard someone effectively. Thoughts like “going on a long vacation without worrying the project will fall apart,” “someone else being able to report updates to management,” and ‘not being the only one who can ship complex features’ start to surface.
You wonder if the advice in this article can help you achieve any of those goals. So far, you haven’t read anything noteworthy. Annoyed and ready to close the tab, you suddenly spot a list of ten items.
Prepare self-paced onboarding questions
Create a list of questions about the project for the new team member to answer independently by exploring the codebase and documentation.
Once they’ve completed it, review their answers, offer clarifications, and gather their feedback on both the project and its documentation.
Eat your own dog food
Have the new team member use the project’s features firsthand. This can vary depending on the project – for example, they might create a collection of requests for each exposed endpoint or build a small client application that integrates with the main project.
History lesson
Share the story of the project, from its inception to the present day. This is a great opportunity to answer questions like:
- What was the original motivation behind the project?
- How has the architecture evolved over time?
- Which features were removed, and why?
- What were the biggest mistakes, and what lessons did you learn from them?
- What major incidents or outages occurred, and how were they resolved?
- And finally, why none of the technical debt is actually your fault—and how things would’ve been much better if they had just listened to you from the start.
Task descriptions
Add sections about motivation and guidelines in the task descriptions.
The motivation section answers why the task needs to be done, and guidelines provide links to resources that can come in handy when solving the task.
Try to reference task IDs in your commit messages or merge requests for future reference.
Keep the project in decent shape
It is not easy to onboard to a big ball of mud. Poorly written projects increase employee churn. The onboardee should be able to get a good understanding of the project by simply looking at the directory structure and reading the names of the modules and interfaces, without going through the low-level implementation details.
Collaborative programming
Pair with the onboardee on coding tasks and organize ensemble programming sessions. After all, it takes a village to raise a child. Collaborative programming is a wonderful way to create a shared mental model of the project and help the new colleague feel like part of the team.
Document use cases and talk to clients
The onboardee should learn what your service does and who it serves. This can be documented in a technical and abstract way through an automated acceptance test suite written from the perspective of an external user of the system.
Additionally, implementing client-focused metrics and creating dashboards can help. If there are actual people who use the features, and there is an opportunity to talk to them directly, take advantage of it and bring the onboardee along.
Deploy it, baby
If you are operating in a “you build it, you run it” environment, create a scenario where the onboardee goes through the entire pipeline – from changing a line of code to deploying to production and observing how the system behaves while processing traffic.
Try to do this as soon as possible. My record is having an onboardee do it on the third day on the job.
Use AI
The year is 2025, and software engineers’ love for automation has gotten out of hand. We are all expected to work diligently on automating ourselves out of work by offloading our responsibilities to unreliable technologies with superior marketing.
Maybe you can feed the project code and documentation to an AI and ask it to handle the onboarding process instead of you? Or, you can just wait a couple of months – after all, we’re about to be replaced anyway, so there’s little point in hiring a new person.
Just-in-time onboarding
For any non-trivial project, it is impossible to explain everything quickly. The onboardee should get enough context to get started, and additional onboarding can be done as the need arises. When you notice that the onboardee is missing context, provide it. Encourage them to ask questions and organize code reviews for the relevant parts of the old code.
*If none of this advice makes sense to you, just follow the golden rule: onboard others as you would like to be onboarded.