Cover image
Engineering Management
10 minute read

Keep Calm and Transition to a New Development Team

Many product owners don’t have a technical background and thus often find themselves unprepared and scrambling when it comes to bringing on a new development team. This often results in hindered progress, wasted time, and frustration for everyone involved. If this sounds like it could be you, either now or in the future, then you should be somewhat concerned. In this blog post, Toptal Freelance Software Engineer Carlos Ramirez III will walk you through the various steps of a typical transition process in project management so you can prepare for this eventuality and make the transition as smooth as possible.

Read the Spanishes version of this article translated by Marisela Ordaz

It is common for a software product to transition from one development team to another during its lifetime. Different stages of the product may call for a different type of development team: a consultancy to build the initial version, a solo freelance developer to maintain it, an in-house team to bring it to scale, or a professional designer to add some “pop”.

Despite how often this occurs, many non-technical founders and product owners find themselves unprepared and scrambling when the time comes to bring on the next team. This often results in an inability for the new team to make fast progress, wasted time, and frustration for everyone involved.

If this sounds like it could be you, either now or in the future, then you should be somewhat concerned. Luckily, we are going to walk through the steps you can take to prepare for this eventuality and make the transition as smooth as possible.

Passing the Torch: Onboarding a New Development Team

In this article, I will provide you with a checklist of items that will help you prepare for such a change. You will be getting to know your product on a more intimate level and gaining more control over all the various services and technologies that go into making it, which will empower you to onboard a new team with confidence and relative ease.

Passing the torch to new developers? Make sure the new team doesn’t get burned and you don’t waste time firefighting.

Passing the torch to new developers? Make sure the new team doesn’t get burned.

But what if you’re not replacing the whole team? Should you bother reading this?

Even if some of the previous team remains on board, they might not have all the answers and information needed for a smooth transition. Although they can provide continuity and aid in the process of transferring knowledge from the old team to the new, relying on incumbent team members is no substitute for the product owner taking charge and facilitating the transfer. In addition, failing to take charge might cause friction between old and new team members, or burden old team members with unnecessary tasks, forcing them to waste too much time communicating with new team members and resolving various issues.

Still, if some team members are staying on board, they can be an invaluable asset in your transition efforts. Consult with them, keep them in the loop and try to leverage their experience without inundating them with too many transition-related tasks. Do not expect them to do all the heavy lifting! That’s your job.

So without further ado, let’s dive in!

Gather Documentation

Freelance developers are often asked to jump into an existing codebase that they’ve never seen before. This is especially true regarding Toptal software engineers. Our goal is always to get up to speed as quickly as possible so we can start having a positive impact for our clients.

Having access to clear, thorough documentation about the project can dramatically accelerate the onboarding process, and help developers avoid pitfalls that can impede forward progress.

Good documentation needs to cover at least the following topics:

  • Setting up a development environment - The first task for any newcomer is getting the application up and running on their own computers. The process for doing so varies between technologies. In general, it requires tasks such as getting the source code, setting up the database, installing dependencies, configuring the environment with API keys and credentials, importing sample data, and so on. Developers have a good idea of everything involved in this process within their respective fields, and should be able to adjust the details accordingly.
  • Running the automated test suite - Seeing an application’s tests pass ensures that everything has been set up properly and that future changes are not breaking any of your existing features.
  • Deploying to the staging and production servers - Updating the live application with the newest changes is a highly scripted process, and the order of those operations should be outlined step-by-step, as detailed as possible.
  • Any other information that is relevant to a newly onboarded developer - Every application has its own set of quirks. Writing those down saves future teams a lot of wasted effort debugging issues that the previous team has already figured out how to deal with.

Good documentation is the cornerstone of any successful transition. Make sure your new team has everything they need to take over.

Good documentation is the cornerstone of any successful transition. Make sure your new team has everything they need.

Documentation should be written by a developer who has first-hand experience setting up the application and contributing to the codebase.

Before any transition occurs, request that the previous development team facilitates the transfer of knowledge by creating a resource that touches on the topics above!

If writing is not their strong suit, ask them to record one or more screencasts demonstrating the development environment setup, deployment, etc. Today there are even tools such as Vagrant and Docker which allow whole development environments to be packaged up and distributed to others. In essence, instead of giving someone directions on how to build a hammer, give them the hammer itself.

The litmus test for how comprehensive and effective a project’s documentation is is how quickly a new developer can get his or her development environment setup and running your application.

Understand Your Product

Having great documentation does not excuse you from needing to know the basics of your own product’s technology. As the owner of a software product, it is your responsibility to understand your application as best you can, even if you aren’t very technical.

No technical background? There's no excuse for failing to properly understand the building blocks of your project. It could cost you dearly.

No technical background? There's no excuse for failing to properly understand the building blocks of your project. It could cost you dearly.

The following questions are common, and you should be expected to know the answers without having to look them up:

  • What technology stack does your application use? - There are many common application frameworks for the back-end and the front-end, and any new development team should have familiarity in the ones your application uses. Some examples of back-end web technologies are Ruby on Rails, Node.js, and Django. Some examples of front-end web technologies are React.js, Angular.js, and Ember.js.
  • Where is it hosted? - Different web hosts have different deployment processes, which require varying levels of experience. In recent years, cloud technologies have created a number of new hosting options, and you’ll need to identify which particular one you are using and describe why it was chosen over the others.
  • What is the development process? - Does your team use a particular source control management tool such as Git? If so, what is the process by which a new feature gets developed, tested, approved, and deployed? The process must be standardized, properly documented, and easy to replicate by newcomers.
  • What third-party services does your application use? - Some applications are built on third-party services such as Shopify. Please keep in mind that reliance on third-party services is gradually increasing, and even if you currently don’t use any extra service, your project may decide to employ a third-party service sometime later.
  • What platforms can your application run on? - Is your app a desktop application, web app, responsive mobile website, native iOS application, native Android application, or anything else? Is it running on several different platforms? Which platform is your priority at any given time? Which platform is your product strongest and weakest on? Be sure to know all the details of your application’s current platforms, and even which ones it can be expanded into.

Take Ownership

Today’s software development process utilizes a plethora of third-party services and tools. Whether you know it or not, your application is no exception.

During the course of development, your previous team may have signed up on your behalf, or even used their own accounts to get access to the services that were needed. Transitioning to a new team means that you must take ownership and be in control of every single one of the services and tools that your application relies on so that you can grant access to your new team without needing to go through a middleman or chase down the original developers.

The following is a list of the various external tools or services that your application might make use of:

Ask your outgoing development team which ones are applicable. For any services which are owned by the development team, ask them to transfer ownership to you. If that’s not possible, then ask them to help you create a new account of your own and ensure that the application uses your account instead of theirs. This should not require anything more than changing some configuration settings for your application.

Needless to say, make sure that every development contract protects your interests from day one and assures a smooth transition, no matter what.

Grant Access

With a solid understanding of the ecosystem of your application and ownership over all the various tools and services your application uses, you are now able to provide full access to the incoming team or individual.

Most services will allow you to add a collaborator to your account and grant them a particular level of access. It’s okay to be conservative here. many founders, especially solo entrepreneurs, prefer to give their developers full administrator access to their services and have them handle everything. This has the negative side-effect of keeping you out of the loop, which as we’ve learned, can make it harder to transition in the future.

Should you give your developers full administrator privileges? It’s your call, and most people don’t have a problem with this approach. However, you always need to plan ahead and make sure your decision does not negatively affect a new development team. Failing to do so in the early stages of the project can have annoying consequences in the future.

Managing the Handoff

Now that you’ve got all your bases covered, you’ll need to manage the handoff from one team to the next. Here are some basic tips for dealing with both the incoming and the outgoing team.

Make sure you properly manage the technical and personal aspects of your project handoff. Make your new team feel at home and don’t antagonize your old team.

Make sure you properly manage the technical and personal aspects of your project handoff. Make your new team feel at home.

Incoming Team

  • Set expectations - The new team should know what your most important goals are so they can focus in the right direction. Managing your own expectations on what the new team can accomplish right away is equally important.
  • Check in often - Don’t leave the new team to sink or swim. You want to check in often to make sure that they have everything they need, and don’t feel like they need to fend for themselves. Try to do this without micromanaging. Make sure they know you are there to support and help if they need, but don’t put unnecessary pressure on them.
  • Be patient - It takes time for developers to get acclimated to a new codebase. Understand that there will be some learning time before the new team can match the pace of the previous one.

Outgoing Team

  • Collect all outstanding code - Make sure all source code is checked into the main repository, and that you know the status of what has or hasn’t been deployed. The new team will need to know exactly where to pick up and start working. I myself have experienced a situation where I took over for a team that had deployed code without putting it in the main repository. This led to bugs, duplicate work, and headaches that could have easily been avoided if the outgoing team left the source code in a consistent state.
  • Update their access level - If you parted ways on good terms, you may want to leave them with access to your code and/or deployment. Many teams are happy to help out during the transition phase until the new team can fully take over. If not, consider downgrading or revoking access to prevent any accidental issues or conflicts with the new team.
  • Thank them for their work - Transitions can be hectic. While you’re busy dealing with the new team, don’t forget to thank your outgoing team for their contribution to your project.


Any transition in life can be scary, bringing the uncertainty of whether or not it will work out, fear of the unknown, and so on. Transitioning to a new development team is no different, but you can and should take steps to make it easier. In most cases, it just requires a bit of long-term planning.

Having a greater technical and non-technical understanding of your software product, the development process, and all the things that went into the process will help make any transition from one team to the next as seamless and painless as possible.

Best of all, your new team will respect and thank you for being on top of your game! You are likely to save them time and effort, which also means you will save money. In addition, the sooner the new team realizes insist on high professional standards, the better. Chances are they will continue implementing these practices once they take over the project, making the next transition smooth as well.

So let’s review the key points that should precede any transfer of ownership of your software product:

  • Collect or create as much documentation as you can about your application, the development environment, and the deployment process.
  • Know your product inside and out.
  • Maintain control of all of your application’s third-party services and dependencies, and have the usernames and passwords for everything.
  • Be ready to give your new team access to everything they need to get up and running.
  • Be proactive and don’t leave anything to chance, or to the outgoing development team.