Checklist for Handing Off a Software Project

We get handed a lot of software projects, and we have to hand off a lot of software projects. Occasionally we get handed a software project or system that is really packaged up nicely, but this is by far the exception.

Usually we have to spend a significant amount of time performing software archaeology in order to figure out how to do basic things like compile the software, set up a development environment, deploy the software, run the tests, etc…

Whether you’re a project manager, team lead, or client stakeholder, we wanted to create a guide that can serve as a checklist for your team (and ours) to make sure that you’re both asking for the right things when you’re taking over a project, and you’re providing the right things when you’re handing off a project.

A lot of these items are just software engineering and documentation best practices, but knowing their importance in the context of a project handoff will hopefully help you find more time for some of these things in the future.

Handing It Off

In any software project handoff, these are the things that we really love to see in any checklist:

Checklist Item 1: Access to previous engineers

This is first on our list because it is the most critical to a smooth transition. I know this isn’t always practical, but when possible, it is the most critical thing you can do to make the transition go smoothly. It doesn’t matter if you have to pay a premium, or keep folks on for a while, you need to do everything you can to make this happen.

Why? In any complex system, there is an unbelievable amount of context that can’t be transferred via static documentation. It is invaluable to have someone around who understands why the system is the way it is, remembers the occasional workarounds that were needed, can quickly get to the root of a system error, knows what stakeholders can quickly answer questions, etc.

Good Ideas:

• Plan for a transition period – Talk with your client about having overlap with the new team. If this isn’t possible, then talk about making someone available in the future when the new team is ready to go. Clients need to understand how critical this continuity is, and it is your responsibility to make sure they understand it. How long to keep an engineer on the project depends on the size and complexity of it. If you have a big and gnarly system, keeping someone from the old team around for 6 months or a year shouldn’t be a problem given the size of the investment you’ve already sunk into it.

Checklist Item 2: A good Readme file

A Readme file that has instructions for how to set up a local development environment, how to deploy the software, and tips for common troubleshooting.

Why? Some pieces of a project, such as the environmental setup, require very detailed instructions that aren’t performed very often. No one will remember these commands or the places where folks got hung up. Worse yet, if you miss some subtle piece of the setup, you may be left with an environment that appears to work correctly, but behaves differently than expected due to missing components or data.

Good Ideas:

• Make sure your organization has a Readme checklist – Readme’s should be a standard part of every project. Make sure your organization has a checklist so that all of the critical pieces are in place.
• Test your documentation – Did you create setup instructions? Great, now go run them on a clean laptop. Did you create deployment instructions? Awesome, now have someone unfamiliar with the project try to follow those instructions to do a deploy. If your instructions aren’t tested, they probably have missing or incomplete steps.
• Setup the project from scratch – I touched on this above, but it is so important that I wanted to call it out. Make sure you can setup your project from scratch on a clean machine. It is highly likely that no one on your team has done this in a while, and so there is a good chance that you’ll run into issues that will need to be addressed.

Checklist Item 3: Codified dependencies

Many software stacks have built-in dependency management, and so using these tools is a good first step. But also make sure that you’re properly pinning versions, so that someone can set up your project in the future without having to guess at versions. If your project has external dependencies, then it is a good idea to either document those, or even better, package them up in a container of some type so that they can easily be set up.

Why? If you don’t have vendored or pinned dependencies, then it can be impossible to recreate an environment from scratch. Especially if a project has been left to sit for a while, this can be a very costly mistake.

Good Ideas:

• Define standard engineering practices around dependencies – Make sure that engineers know that dependencies should be in code, versioned, and locked. You need to be able to build your source two days from now and two years from now on a clean machine.

Checklist Item 4: Automated Tests

Documentation is great, but it is really difficult to keep up to date. It also rarely describes in any kind of detail how the engineers expected individual pieces of the system to function. Tests do exactly that. They describe in a very granular way how an engineer expected the system to function.

Why? Oh, the age old question. Tests are executable documentation. They describe what your system does, how the engineer expected it to work, and whether it still matches those expectations. Can you screw tests up? Sure! But without tests you’re flying blind, and you’re missing a valuable piece of documentation to ease a handoff.

Good Ideas:

• Cleanup tests before handoff – Go through your test suite and clean up the tests. Look for useless tests, commented out tests, tests that are poorly formatted.
• Increase test coverage – I know, this is way easier said than done. But look for areas that have particularly low coverage, and think about what tests can help express the intent of the system. You might also find a few bugs while you’re in there.

Checklist Item 5: Testing/Integration environments

When taking over a new project, it is critical to be able test new changes within a realistic environment that is similar to your production environment. Otherwise you could be in for some nasty surprises.

Why? Worked on my machine! Having testing/integration/staging environments that closely mimic production is always a great idea, but even more so when you’re making changes to an application that you’re not intimately familiar with. As any software engineer will tell you, just because it works on your local machine doesn’t mean it’ll work in a deployed environment.

Good Ideas:

• Transfer testing/integration environments – It is almost impossible for a new team to ship new features without a good testing/integration environment. Imagine coming into a large application, having to make changes and just push it live? For most software engineers, that is the definition of a nightmare.

Checklist Item 6: Account access

It can be a real pain if you take over an application that is hooked up to Twilio, AWS, Sentry, Mailchimp, Sendgrid, Loggly, etc… and you have to go through and reconnect everything to new accounts because you weren’t provided with access to the old accounts. Doing this can be both time consuming and risk.

Why? You’ll likely need to change credentials during any transition, since you can’t guarantee that the previous team didn’t leave them on a sticky note on their monitors, but it would still be nice to have access to all of that data! If that app is using an error monitoring tool, it is good to be able to use the same account so you can see historical error trends.

Good Ideas:

• Make account info easily transferable – Make sure that all of the services you use for customer projects are kept in their own accounts that can just be handed over. If you use shared accounts you’ll create headaches for yourself and your clients.
• Use an email alias – Where it makes sense, use an email alias to sign up for services and accounts. Also use an alias for notifications. That can make it easier to hand over an account when necessary.

Checklist Item 7: Documentation of assets outside of the source control repository

Applications almost always have things that live outside of source control. Do you have Google Sheets where you manage some account data, do you have documentation in a collaboration tool that outlines customer support procedures, do you have design files that might be needed if some application assets need to be updated?

Why? When dealing with software projects, most engineers think of the source code! Engineers are going to look at things from an engineering perspective, and sometimes that means that other assets can get overlooked. It is important to think about the overall context of the system: who is using it, how it is used, how it was designed, etc…

Good Ideas:

• Walkthroughs of application usage – One of the fastest ways to help someone come up to speed in a new application is for them to understand it from a user’s perspective. That can be hard without business knowledge, so walking them through the app from a user’s perspective can be critical. If you can’t do it live, record a screenshare of it.
• Keep all of your design/discovery/technical documentation in one place – Throw it in a shared Dropbox folder, in Google Drive, or wherever. Just make sure that it is all in one place and can be handed over when needed.
• Environmental documentation – Your infrastructure should be source-controlled, but there are always pieces of the puzzle that don’t fit into your AWS account. Try to have some documentation around the different pieces of your environment, what they do, how they fit together, and what kind of external services are leveraged.

Checklist Item 8: A little housekeeping

It never hurts to do a little housekeeping. Clean up things like unused classes that are no longer needed, features that can’t be reached from the UI, tables or columns in the database that are no longer used, background jobs that don’t run anymore, user roles that aren’t needed, unused api keys, etc… the list could go on and on. I hope you don’t have these things laying around, but I’ve seen enough applications to know that these are issues all over the place.

Why? Sometimes we let things build up in our projects that we ignore, but for someone new coming into the project they will confuse them or send them down dead ends. Is this table used? It can be really hard to tell. How about this user? I’m scared to delete it because it could be used somewhere that I can’t find. These kinds of issues can cost engineers a lot of time, energy, and stress.

Good Ideas:

• Clean up dead branches – have working branches that someone didn’t clean up but you know they aren’t being used, just delete them.
• Document in-process branches – Have some branches with in-process work that you know could be used, but was never pulled across the finish line. Open a pull request and add some notes!
• Clean up dead code/database artifacts – Do you know of classes that aren’t used, database columns that are no longer needed, etc… make a note to clean them up or document the fact that they can be safely removed.
• Document unused functionality or systems – Do you know of functionality within the system that was used at some point, but isn’t anymore and could be removed? Do you know of microservices that no longer serve a purpose? Make a note of it, or better yet, remove it if you can.

Checklist Item 9: Project history

Access to anything that recorded the history of the project. Previous project management tools, chat logs, source history, bug trackers, etc… Even if you’re using new tools, it is important to have access to historical tools.

Why? This will make it easier to determine if there was unfinished work, see what the latest changes were made to the project, see who was involved, and it will also provide a huge amount of context as to how the application evolved. Being able to find a story where a feature was implemented and read the notes and comments on it could be very valuable in the future!

Good Ideas:

• Just ask for access – Hopefully the project is easy to hand off, and if not, just ask for an export. Maybe you won’t need it, but it is always a good safety net.

Don’t Ruin a Great Project with a Bad Handoff

One of the most important tasks of any consulting team is to treat project handoffs with care and respect. You’ve done all of this great work, now don’t make yourselves look bad by handing off the project in a sloppy way to your client or new team. Using the above checklist, try to make sure you cover as much of the list above as possible. Don’t beat yourself up if you can’t get to everything, but the more items you cover, the more smoothly your handoff will go.