Whether you are adding a new hire or an existing employee, proper on-boarding of new team members is crucial to the success of your project.  A key component of Intelliware’s on-boarding process focuses on the “soft-side” aspects, such as knowledge transfer on the business domain, architecture, tools and frameworks, and team processes.  Getting up to speed on these aspects of the project will help both new hires and existing employees moving to new projects become effective quickly.  Below I have outlined a few tips and tricks that I’ve learned over my many years in software development that can help make on-boarding a new team member successful.

Project Overview

New members need to fully understand the business problem that the team is trying to solve.  A great starting point is to organize an overview meeting with the entire team.  The discussion should focus on the following two questions:

1. Why are we here?

2. What are we trying to build?

I have found that the best team members to facilitate this discussion are the Product Owner, Technical Lead or Business Analyst.   These roles are best equipped to cover the project’s business domain from a technical perspective. More than one meeting may be needed to cover the breadth of information to be discussed.

I have also found that it is helpful, as part of the project overview meeting, to provide documentation that outlines the project’s business domain and a glossary of relative business terms.  The glossary is helpful because often, business domains, such as Financial Services and Healthcare, use specific terms that new team members may not be familiar with.  The documentation provided should focus on the problem being solved because this is the focus of the overview meeting.

Project Architecture Overview

It’s important when on-boarding new team members for them to understand how the scope of the project fits into the bigger ecosystem and how what the team is building will interact with other systems.  The following questions can help new team members learn more about these two topics:

  • What’s the composition of the software that we are building?
  • What does the runtime environment look like?
  • Can we get more details on how the system is designed?

There are various ways to communicate how a system architected; a method that I found quite useful is the C4 model.

The C4 model illustrates the architecture of a system from four logical perspectives:

1. Level 1: A System Context Diagram

2. Level 2: A Container Diagram

3. Level 3: A Component Diagram

4. Level 4: A Code level diagram (like a UML sequence diagram)

An architecture overview for new team members could be delivered by the Architect, Tech Lead, or even a Developer.  A Developer being able to lead this discussion is a good indicator of how well the team, as a whole, understands the system architecture.

Tools and Frameworks

New team members need to be familiar with the tools and frameworks being used for the build.  Different projects will use a wide variety of technologies for front ends, back ends, and data stores; new team members need to have a clear understanding of how these tools and frameworks work together to deploy the system successfully.  The team has a role to play in ensuring that new members are sufficiently familiar with the project’s technologies and providing, in cases where there are knowledge gaps, appropriate training to get them up to speed.  I recommend that teams maintain an inventory of courses and resources for their technologies that new members can refer to for filling knowledge gaps.  If such a list doesn’t exist at the beginning of a project, the team should aim to build one as they collectively learn about the project’s tools and frameworks and discover resources useful to others in the future.  A variety of resources is helpful for team members that have different ways that they learn effectively.

Setting up Development Machines

New team members, especially developers, will need correctly functioning development machines.  A new developer, when fully on-boarded, needs to be able to build the application, run tests, and run the system locally.  I have found it helpful to write up instructions on how to set up a development machine based on the project’s technologies and run the application locally.  The best place to keep this documentation is in the project’s code repository.  If your project has multiple repositories or external dependencies, it might be useful to create an umbrella document that outlines putting the higher-level pieces together. Making it easy for team members to set up and run the project will save time when a new person joins the team.

A complex project setup will slow down development and can indicate an overly-complicated system architecture and codebase. Associated project documentation will also be overly complicated and inherently hard to maintain.  These challenges are exacerbated in the age of COVID-19, with everyone now working remotely; it’s harder to get another team member to show you how to set up the development environment.

On-boarding new team members can be facilitated by isolating the system from external dependencies to make it easier to run the application locally, especially in situations when there are many external dependencies.  For example, I’ve had success using mock servers, such as WireMock, to mimic external APIs.  Another useful approach is to use Docker images for external dependencies, such as Databases or Messaging Systems, so that team members can avoid having to install them on their local machines.

Learn the DevOps Side of the Project

Nowadays, modern projects will include DevOps aspects.  New team members will need to learn what DevOps tools and technologies are in use.  The following questions outline some DevOps-related project aspects that new developers on a team should consider:

1. What is the project’s build pipeline?

2. Does the system integrate with repositories directly (ex; BitBucket or GitLab), or are external tools, like Jenkinsor TeamCity, required?

3. How are changes made to the pipeline, if needed?

4. Are code quality measures included as part of the build pipeline, such as test coverage and code scans?

5. Are there ways to make sure code quality is good enough to pass the checks on the pipeline before it gets pushed? For example, tools for checking test coverage locally, Linting rules, and SonarQube plugins?

6. How can the code be deployed to different environments?

7. Are there any monitoring tools? How to access logs when something goes wrong?

I find it helpful to create a visual diagram to represent the DevOps pipeline for a project.  As an example, on one project, my team created this simple diagram using PowerPoint SmartArt to illustrate our DevOps pipeline:

Learn the Process

New team members need to learn the process that the team is following to be successful.  Below, I’ve listed some questions that new members, and the team as a whole, should consider during the on-boarding process:

  • What are our team norms?
  • When is our daily standup meeting? What types of information do we talk about in the standup?
  • How do we do tasking (aka story opening)? For example, in one of my previous projects, we ensured that 80% of the team was available for tasking and had at least one representative from the business present.
  • Where do we record tasks? On Jira, on a shared Excel document, or is the tasks list on a physical whiteboard?
  • What do we use for issue tracking? What is the workflow that we follow for issues, and when do we update each story?
  • Do we create feature branches and PRs (Pull Requests), or does every push go to the mainline directly?
  • What’s the review process for PRs? Can anyone in the team be an approver? Do they require single or multiple approvers?
  • What’s the preferred method of communication within the team? Especially with people working remotely, what’s the most effective way for the team to engage them? Chats, phone calls, or video calls?
  • Do we prefer to have one-one conversations, or are group chats preferred? I like and recommend video calls and phone calls instead of chats for technical discussions.

It’s important to discuss these considerations upfront and make sure new team members have a good understanding of team norms and processes to avoid and ambiguity and future confusion.

Learn the Organization’s Tools

If your team is working in or with a large organization, such as a Financial Institution, there are usually organization-specific tools that new members will need to be aware of and access.  How the team member uses the tools and accesses them will depend on their role on the team. 

On-boarding Activities as Tasks

A great way to organize and prioritize various on-boarding activities is to treat them similar to other work that the team must do by adding on-boarding tasks to the team’s stories.  I have found it helpful to have a list of activities that focus on the soft side of on-boarding and keep these activities in mind during tasking meetings.  Adding on-boarding tasks to stories that the team is currently working on provides the following advantages:

1. Makes the tasks visible to the team, so everyone will know what needs to be done to on-board the new team member, and what activities are still outstanding

2. Gets the new team member involved with story work, which helps them engage in active work and get up to speed more quickly. This is much better than having a new team member shuffled off to the side to work on their own on-boarding activities (which is especially pertinent during COVID-19, when teams are mostly working remotely).

Including on-boarding tasks as part of the team’s process helps ensure that everything gets done, makes the process repeatable, and facilitates an inspect and adapt cycle to help keep the process up to date and relevant. Keep in mind to refresh these tasks each time a new person is on-boarded, as it’s inevitable that the business and technical context of the project will evolve over the course of the project and consequently, these tasks need to be updated to match the current context of the project.


Remember that all of the on-boarding tasks noted in this article do not need to be completed in one day; sometimes, it can take many days to on-board a new team member, especially on large, complex and legacy projects.  Also, the tasks do not need to be done in a specific order.  The team will know best how to set priorities.  Keep in mind that these activities will vary by project. In some cases, it’s useful to go through the entire list explicitly with the new members, and other times it makes more sense to delay some activities or assume that their outcomes will be achieved as part of day-to-day project activities. Finally, while it’s good to have a framework for on-boarding new team members, this shouldn’t cause other simple and effective tools to be avoided, such as Pair Programming for knowledge sharing.