What a good software handover should contain
The seven artifacts an outgoing developer or agency should hand over with a software system: access, environment map, operating manual, architecture notes, decision log, open issues, and a recorded walkthrough.
Paul BădărăuA software handover is complete when the incoming team can deploy, restore, and change the system without contacting the outgoing one. Most handovers deliver a repository and a goodbye. This is what a good one contains, in the order the incoming team will need it.
Use this list in two directions. If you are leaving a system, deliver these seven things. If you are receiving one, ask for them by name before the previous team's last day, because after that day every item costs ten times more to recover.
1. Transferred ownership of every account
Not shared logins: ownership. Repositories, hosting, DNS and registrar, databases, object storage, email delivery, payment providers, third-party APIs, app store accounts, monitoring, and any SaaS the system depends on, each transferred to an account controlled by the company that owns the software. A spreadsheet listing each service, its purpose, the owning account, the payment method, and the renewal date is the single most valuable document in the handover.
2. An environment map
One page that answers: what runs where. Production, staging, and any other environments; the servers or platforms behind each; the databases and stores they use; the scheduled jobs and where they are configured; the external services called and the services that call in. A diagram helps, but a list is enough. The test is whether an engineer who has never seen the system can point at every moving part.
3. An operating manual
How to deploy a change, and how to roll one back. How to restore a backup, with the last date it was rehearsed. How to rotate each secret. How to add an administrator. What to do when the site is down, the queue is stuck, or the database is full. Who to call at each provider. This document is short and boring, and its absence is why most inherited systems have their first outage in the first month.
4. Architecture notes
Not a specification. A few pages on how the system is put together and why: the main components, how a request travels through them, where the data lives, the parts that are fragile, and the parts nobody should touch without reading the notes first. Written by the people leaving, while they still remember.
5. A decision log
The decisions that shaped the system and the reasons behind them: why this database, why this hosting, why this framework, why that integration was built in-house. The reasons matter more than the decisions. A decision without its reason gets reversed by the next team for the same reason it was made.
6. The open issues, honestly
Known bugs, workarounds in place, deferred upgrades, dependencies near end of life, security concerns, and the things that keep the outgoing engineers up at night. An honest list here saves the incoming team months of discovery and protects the outgoing team's reputation when the issues surface anyway.
7. A recorded walkthrough and a question window
One or two recorded sessions walking through the environment map, the deployment, and the architecture notes, with questions. Then an agreed window, paid if necessary, during which the outgoing team answers questions by email. A few hours of the previous developer's time are worth weeks of archaeology.
What to do if you receive less than this
Most incoming teams receive item one partially and nothing else. In that case, run the codebase takeover checklist yourself and write these seven artifacts as you go. The first three are urgent; the rest can follow in the first months.
If you would rather have the incoming team be us, software takeover is the service, and producing this handover for the next team is part of how we finish it.