What a handover has to achieve
Handover happens at several moments in a system's life: when a build finishes and moves to a support team, when a company brings development in-house, when one supplier replaces another, or when the person who wrote an internal tool leaves. The circumstances differ and the risk is the same. Knowledge that was never written down leaves with the people who hold it.
The purpose of a handover is therefore not to deliver files. It is to transfer the ability to operate and change the system. Judging it by that standard changes what you ask for, and it gives you a clear test of whether it worked.
The six things that must change hands
| What | Includes | Commonly missed |
|---|---|---|
| Source code | Every repository, with full history and branches | Scripts, infrastructure definitions and small utilities kept elsewhere |
| Accounts and access | Hosting, domains, app stores, email, payments, analytics, third-party services | Accounts registered in a developer's own name |
| Environments | Production, staging and the way to create a new one | Configuration values and secrets that exist only on a server |
| Documentation | Architecture, setup, deployment, operations and known issues | Why decisions were made, not only what they were |
| Data | Databases, files, backups and how to restore them | A restore that has actually been tried |
| Knowledge | How the system behaves in practice, and where it is fragile | The workarounds everyone on the old team simply knows |
Ask early whose name each account is in. Moving a domain, an app store listing or a payment account between legal owners can take time and paperwork, and is far easier while everyone is still cooperating.
Test it with a real change
A handover document can be complete and still fail, because nobody discovers the missing step until they need it. The reliable test is practical. Before the outgoing team leaves, the receiving team should do three things by themselves, using only what was handed over.
- 01
Set up a working copy from nothing
On a clean machine, follow the setup instructions until the system runs. Every question that has to be asked is a gap in the documentation, and should be written into it.
- 02
Make and deploy a small change
Change something visible and harmless, take it through testing and release it to production. This proves access, tooling and the deployment process in one exercise.
- 03
Restore from a backup
Recover the database into a test environment and confirm that the application works with it. A backup that has never been restored is a hope, not a safeguard.
A worked example
A booking platform moving from an agency to an in-house team
This example is invented. A company that runs a booking platform hires two developers and takes over from the agency that built it. Both sides are cooperative, and the handover still turns up surprises.
- CodeThe main repository is transferred with its history. The clean setup reveals a second repository for the admin tool and a set of scheduled scripts on the server that were never in version control.
- AccountsHosting and the domain are already in the company's name. The text message service and the map service are on the agency's own accounts, shared with other projects, and need new accounts and new keys.
- DeploymentThe new team's first release fails because one configuration value exists only on the production server. It is added to the documented list of settings.
- KnowledgeIn a recorded walkthrough the agency's lead developer explains why bookings are locked for a short period during payment. Nothing in the code or the documents said so.
The overlap lasts three weeks instead of the one that was planned, and ends when the in-house team has released twice and restored a backup without help. The list of gaps found along the way becomes the first section of the new team's own documentation.
What the documentation needs to say
Useful handover documentation is short and specific. Nobody reads a hundred pages, and a long document is usually out of date. Aim for a set of plain pages that answer the questions a new developer asks in their first days.
- 01
What does this system do, and for whom?
A useful page coversThe purpose, the main users and the business processes that depend on it, in a page.
- 02
How do the parts fit together?
A useful page coversA diagram of the components and the outside services they call, with what happens if each one is unavailable.
- 03
How do I run it and release it?
A useful page coversSetup from an empty machine, the test commands, the release steps and how to roll back.
- 04
What needs regular attention?
A useful page coversScheduled jobs, certificates and subscriptions that expire, and what to check each week.
- 05
Where is it fragile?
A useful page coversKnown problems, parts nobody likes to touch, and the reasons behind decisions that look odd.
The handover checklist
Software handover checklist
0 of 11 checkedWhen the handover is not friendly
Sometimes a handover happens because the relationship has broken down, or the previous developer is no longer reachable. The checklist still applies, in a different order. Secure access first: domains, hosting, repositories and stores. Then take a full copy of code and data. Only then start trying to understand it.
You are in a workable position
- The domain and hosting are in your company's name
- You can reach the repository and the production servers
- A recent backup exists and can be opened
Act before anything else
- Key accounts belong to a person or supplier you cannot reach
- The only copy of the code is on a running server
- Nobody knows where backups are kept, or whether there are any
What you are entitled to receive depends on your contract, so read it, and take legal advice if access is being withheld. Our project rescue service covers the technical side of taking over a system in this state.
What to do next
If a handover is coming, copy the checklist and fill in the account list first. It is the item most likely to hold surprises, and the one that takes longest to put right.
If you are receiving a system and would like a second pair of eyes, a technical code audit tells you what you have been given. Tell us about the system and we will suggest where to start.
Common questions
How long should a software handover take?
It depends on the size of the system and how well it was documented, so there is no single answer. What matters is that the outgoing team remains available until the receiving team has set the system up, released a change and restored a backup by themselves. Plan the overlap around those three milestones instead of a fixed date, and expect it to run longer than first estimated.
What if the previous developer will not cooperate?
Secure what you can reach, starting with domains, hosting and repositories, and take copies of code and data. Check your contract for what you are entitled to, and take legal advice if access is refused. Technically, a system can usually be understood from its code and its running environment, though it takes longer. An independent audit is a sensible first step.
Who should own the accounts and services?
The company that depends on the system should hold the accounts in its own name, with access granted to whoever builds and maintains it. That covers domains, hosting, app store listings, payment providers and other paid services. Accounts held by a supplier or an individual are the most common cause of painful handovers. The terms are a matter for your agreement with the supplier.
Do we need documentation if the code is clean?
Yes. Clean code shows what the system does. It rarely shows why a decision was made, how to release, which outside services are involved or what must be checked every week. A few short pages on those subjects save a new team days, and they matter most at the moment when the people who could have answered are no longer there.
Should credentials be changed after a handover?
Yes, once the receiving team has confirmed that everything works. Passwords, keys and tokens that the outgoing team held should be replaced, and their user accounts removed or reduced. This is ordinary good practice and no reflection on anyone's honesty. Schedule it as an explicit step, because it is easily forgotten once the system is running smoothly.
