Handing a project over to someone else

When you need this

Leaving a team, changing jobs, tiring of your own project and passing it to someone willing, taking a month off.

A bad handover looks like this: the person gets a repository link and the words "it's all fairly clear". A week later they can't run it and you're unreachable.

What to prepare

Working setup instructions. Verify them on a clean machine. It almost always turns out something is missing: you installed it long ago and forgot.

A list of access. Where the hosting is, the database, the mail, the domain, the accounts for external services. With a note on how the keys themselves are transferred — not as chat messages.

A description in broad strokes. What the parts are, where things live, what to look at first.

A list of known problems. Honestly: what works awkwardly, what's temporary, where the workaround is and why.

What's planned. Prioritised tasks, so they understand where it's all heading.

What to say out loud

Some things are in neither the code nor the documentation:

Why it was done this way. "This looks odd because of the following history."

Where not to poke. "This part is fragile, it's tied to that, better not touch it without need."

What breaks regularly. "Once a month this falls over; here's how to fix it."

Who the important people are. Who to message about hosting, who understands that part.

An hour of conversation is enough, and it saves the new person weeks.

The order of a handover

Getting it running first. Have them start the project on their own machine while you're available. That exposes every hole in the instructions.

Then a small task. Have them build something small and ship it end to end, themselves, while you're around to advise.

Then the explanation. Structure, decisions, weak spots. After they've touched it with their hands the explanation lands rather than sailing past.

Then a support period. A week or two where you still answer questions but don't do the work.

How to know it happened

A simple test: they shipped a change to production on their own. Not read the code, not nodded on a call, but travelled the whole route.

Until that happens the handover isn't complete, whatever it feels like.

What not to do

Don't dump everything into one conversation. Three hours of talking won't be retained.

Don't hand over "when there's time". Set dates, or it stretches until you leave and never happens.

Don't keep the access on your accounts. In a month nobody will find you, and the key will be needed.

Don't pretend everything is perfect. Say what the workarounds are. They'll be found regardless, but without an explanation of why they exist.

The other side

If you're the one receiving a project, demand exactly the same. Instructions, access, a conversation, a support period.

And ask the question people forget: what breaks here most often and why. The answer is more useful than any architecture diagram.