What should be in a proper handoff when a software project is delivered?
A usable handoff lets a developer who has never seen the system get it running, deploy a change, and diagnose a failure without calling anyone. That means an architecture summary, a local setup guide, a deployment procedure, an inventory of scheduled jobs and integrations, credential locations, and a list of known failure modes with responses. A code archive alone is not a handoff.
The test the handoff has to pass
There is one standard worth applying: a competent developer with no prior exposure, given only the documents, can get the system running and ship a small change.
Everything else is negotiable. If the package cannot pass that test, it is a filing exercise. The way to verify it is to actually try it before the original team is gone, not after.
What belongs in the package
- An architecture page. One diagram and one page of prose. What the pieces are, what talks to what, and where data enters and leaves.
- Local setup. Exact steps from a clean machine to a running system, including how to get safe test data.
- Deployment. How a change reaches production, who can do it, and how to roll back.
- An integration inventory. Every external system, what it is used for, which credentials it uses, its rate limits, and the contact or account that owns it.
- A scheduled job inventory. What runs, when, what it does, and what happens if it does not run.
- Known failure modes. The things that break in normal operation and the standard response to each.
The undocumented decisions are the valuable part
Most handoffs describe what the system does, which a developer could work out from the code. The scarce information is why it does it that way.
Why this data is denormalized. Why this job runs at that hour. Why this field is stored as text. Why the sync deliberately skips a record type. Every one of those is a decision that looks like a mistake to a newcomer, and someone will helpfully fix it and break something. A short decisions file with a line of rationale each prevents more damage than any amount of API documentation.
Handoff is a practice, not an event
Documentation written at the end of a project is written by people who are already mentally elsewhere, and it goes stale immediately. Documentation written as work happens stays accurate because it is used.
The workable habit is to keep the runbook in the repository next to the code and update it in the same change that alters behavior. That is how a custom build stays transferable, and it is a fair thing to require of any partner. It also means you are never negotiating for documentation at the moment your leverage is lowest — which is the real reason to insist on it early, alongside access to your own integrations and accounts.
Topics: handoff · documentation · operations · runbook
Have a version of this question about your own business?
The useful answer usually depends on which systems you run and how they're connected. That's a conversation, not a blog post.