Developer handoff documentation: how to hand over a project properly

A handoff fails quietly. Everything looks fine until the first incident, when the one person who knew why the cron job runs at 03:10 is on another team or gone.

By the VeoRec team · Oct 3, 2026 · 12 min read

Developer handoff documentation is the stuff you wish existed the first time you inherited a project: what state it is in, why it is built this way, how to deploy it, what breaks, and who to ask. It rarely exists, because handoffs tend to happen in a rush. Someone changes team, goes on leave, or leaves the company, and the knowledge transfer gets squeezed into a one-hour call and a Notion page titled "Notes".

The structure below is the one we would want handed to us. It is written for the person leaving, but the person arriving can use it as a list of things to ask for, and it holds whether the receiver is a teammate, a new hire or an outside agency. The examples come from a billing web service; swap in your own mobile app or data pipeline and the sections stay the same.

Know what a handoff has to transfer

Most handoff docs cover how the code is organised and stop there. That is the part the new owner could work out alone. The expensive parts are the ones that live in someone's head. A complete handoff transfers five things:

Google's book on its engineering practice has a chapter on knowledge sharing that makes a useful distinction between knowledge held by people and knowledge that is written down, and argues the two complement each other rather than one replacing the other (Software Engineering at Google, chapter 3). A handoff is the moment the person-held part is about to disappear, so the job is to move as much of it as possible into writing and recordings while the person is still around to answer questions.

Start two weeks out, not on the last day

A handoff squeezed into the last two days produces a document nobody has tested. The new owner reads it, nods, and discovers the gaps during the first incident, when the previous owner is no longer reachable. Spread it out instead. A timeline that works for most services:

1. Two weeks out: write the skeleton The person leaving fills in the handoff doc below, quickly and roughly. Links matter more than prose at this stage. They also start a list of "things I would tell you over coffee".
2. Ten days out: record the tours A system tour, a deploy, and one or two walkthroughs of known problems. Each is a short recording; more on what to record below.
3. One week out: shadow The new owner joins the current owner for real work: a deploy, a support ticket, a review. They take notes on everything that is not in the doc.
4. Last few days: reverse shadow The new owner does the work, the current owner watches and stays quiet unless something is about to go wrong. Gaps in the doc show up fast.
5. After the handoff: one check-in Two or three weeks later, a 30-minute call (if the previous owner is still reachable) to clear up whatever surfaced. Record it or write up the answers.

If you do not have two weeks, compress the steps but keep the order. A rough doc plus a few recordings plus one reverse-shadowed deploy beats a polished doc nobody has tried to use.

Write the handoff document as a map, not an encyclopedia

The handoff doc should fit on a few screens. Its job is to point at things: the repo, the dashboards, the runbook, the decision log, the people. If it tries to explain everything, it will be out of date before the person leaving has finished writing it.

Keep it next to the code if you can (a HANDOFF.md or a section of the README), so it gets versioned and reviewed like everything else. A wiki is fine if that is where your team actually looks. What matters is that the new owner can find it in six months without asking.

Here is a template. Delete the sections that do not apply; do not leave them empty, because empty sections look like someone forgot.

Keep a decisions log so the reasons survive

The question new owners ask most is not "how does this work?" but "why is it like this?". Why is there a second queue? Why does this service call the database directly instead of going through the API? Without the reason, the new owner has two bad choices: leave strange code alone forever, or "clean it up" and rediscover the problem it was solving. (Michael Nygard describes the same trap: blindly accepting a decision, or blindly changing it.)

The lightest structure for this is the architecture decision record, which Michael Nygard described in 2011: a short numbered file per decision, with a title, the context, the decision, a status and the consequences, kept in the repository. Old decisions are not deleted when they change; they are marked as superseded, so the history stays readable.

If the project has no decision records, do not try to backfill all of them during a handoff. Write the five or six decisions the new owner is most likely to question. A good way to find them: ask the person leaving which parts of the code they would warn a newcomer not to "simplify".

Record what text explains badly

Some knowledge is painful to write and quick to show. A system tour, where you open the repo, the dashboards and the logs and narrate how a request flows through them, takes an hour to write well and ten minutes to record. The same goes for a deploy with its little rituals, or the way you debug the one problem that keeps coming back.

The recordings worth making in almost every handoff:

• The system tour (10 to 15 minutes). Follow one real request from the browser or the client to the database and back. Open each service as you pass through it. Name the things that are surprising.
• The deploy and the rollback (5 minutes). Do a real deploy on screen. Say what you check before and after. Show where you would look if it went wrong, and how you roll back.
• One recording per recurring problem (3 to 5 minutes each). "The import job stalls about once a month. Here is how I spot it, here is the query I run, here is how I restart it."
• The work in progress (5 minutes). Open each branch or draft pull request and say where it stands and what is left.

Long tours need chapters, or nobody will find the part they need three months later. In VeoRec's screen recorder for developers you press M while recording to drop a marker and name it on the finish screen; on Pro, AI chapters are generated after each recording. A system tour with chapters might look like this:

Date every recording and say what it assumes

Recordings go stale in a way that is harder to spot than stale text. A wiki page with an old version number looks old; a video of an old dashboard looks perfectly confident. Say the date and the context in the first ten seconds: "This is the deploy as of October, on the old pipeline, before we move to the new runner." When something changes, re-record the short video rather than adding a note that says "ignore the part at 3:20".

Short recordings make this cheap. Five four-minute videos are easier to keep current than one twenty-minute video, because when the deploy changes you replace one of them and leave the rest alone.

Every recording should be findable from the handoff doc, with one line saying what it covers and when it was recorded. Automatic transcripts help here: a new owner can search the recordings for "reconciliation" and land on the right minute instead of rewatching everything. The post on searchable video transcripts shows how that works. If you are new to recording code, how to record your IDE and terminal covers the settings that keep code readable.

List the gotchas you would tell someone over coffee

Every system has a handful of things that are not bugs exactly, not documented anywhere, and absolutely will bite the next person. The staging database gets reset every Sunday. The integration tests fail if run between 23:00 and midnight UTC because of a date boundary. The vendor's sandbox goes down every few weeks and the tests that depend on it are marked flaky for that reason.

These are the hardest things to get out of someone's head, because they no longer notice them. Three prompts help:

• What do you check manually that a newcomer would not know to check?
• Which alerts do you ignore, and why is it safe to ignore them?
• What did you get wrong in your first month on this project?

Write each answer as a sharp edge entry (there is a template above): the symptom, when it happens, why, what to do, and whether a permanent fix is planned. Symptom first, because that is what the new owner will be searching for when it happens.

In practice, the note most people leave is "Reconciliation job is a bit flaky, just rerun it." The entry that actually helps at two in the morning reads like this:

The second version tells the new owner whether to panic (no), what to type, how long to wait and why nobody has fixed it. That last part stops a well-meaning newcomer from spending a week on a rewrite the team already decided against.

Hand over access, ownership and the boring admin

The handoff failures that hurt most are often about access, not knowledge. Three weeks after the handoff, a TLS certificate expires, and the only person with admin on the DNS provider has moved on. Go through the list explicitly:

• Code ownership. Update CODEOWNERS (or your equivalent) so the new owner is requested for review automatically. GitHub documents how the file works and where it can live (GitHub docs).
• On-call and alerts. Move the rotation, the alert routing and any personal notification rules. Check that alerts actually reach the new person.
• Third-party accounts. Payment provider, email service, error tracker, analytics, app stores, domain registrar. Who is admin? Is there a second admin?
• Scheduled jobs and their owners. Cron jobs, scheduled workflows, nightly exports. Note what runs, when, and what breaks if it stops.
• Credentials. Move them through your password manager or secrets store. Never paste them into the handoff doc, a chat thread or a recording.
• Promises. Commitments to other teams, customers or the business. These are part of the handover too.

Overlap: shadow first, then reverse the roles

Documents and recordings get the new owner to "I think I understand." Overlap gets them to "I have done it." Plan for both, shadowing first.

Shadowing: the new owner watches the current owner do real work. Not a demo, the actual deploy of the week, the actual support ticket. The new owner writes down every step that is not in the doc, and every question that comes up. Those notes go straight into the doc.

Reverse shadowing: the new owner drives, the current owner watches. This is where the real gaps show up, because the new owner hits every unwritten assumption. The person leaving should resist the urge to take the keyboard; a question answered out loud is worth more than a fix done for them.

If the two people are in different time zones, recordings can stand in for some of the shadowing. The current owner records the deploy as they do it; the new owner does the next deploy and records it too, and the current owner leaves timestamped comments on anything they would have done differently. It is slower than sitting together, but it works, and it leaves a record. In VeoRec those comments sit at the exact second they refer to and can be marked resolved once the doc is updated, so the review of the deploy doubles as a to-do list for the handoff doc.

Check that the handoff actually worked

A handoff is done when the new owner can do the job without the old owner, not when the doc is written. Use the checklist below as the finish line, and tick items only when the new owner has done them alone.

The last item matters more than it looks. When the new owner edits the doc, it stops being the previous owner's notes and becomes the team's documentation. If nothing in it needed correcting, it probably was not read closely.

When the previous owner is already gone

Sometimes you inherit a project with nobody to ask. The same structure still helps; you are just writing the doc for yourself and your successor.

1. Start with ownership and access. Find out who has admin on everything before you need it in an emergency.
2. Read the last three months of merged pull requests and incidents. They tell you what was changing and what was breaking.
3. Do a deploy early, while nothing is on fire, and record it. That recording becomes the first entry in the new runbook.
4. Write decision records as you discover the reasons. "We think this is cached because of X; not confirmed" is still useful.
5. Keep the sharp edges list from day one. Your first month is when you notice the strange things; by month three they will feel normal.

Recording your own exploration as you go (a five-minute "here is what I found today" video) costs little and gives the next person a head start you never had.

What to do this week

If a handoff is coming up: copy the handoff doc template, fill in the "Where things are" section in twenty minutes, and book the shadowing and reverse shadowing sessions now, before calendars fill up. Record the system tour next; it is the single recording that saves the most questions.

If no handoff is planned: that is the best time to do the cheap parts. Write the five decision records you would want explained, record one deploy, and update CODEOWNERS. Teams change faster than anyone plans for, and the same material doubles as onboarding for the next engineer who joins. If the handoff is between QA and development rather than between developers, the QA to developer handoff checklist covers that case.