One of our best people is leaving Autonomous.
He's been here long enough that his fingerprints are on a lot of things. Not just code - decisions. Patterns. The way we handle certain edge cases. The reasons behind choices that, on paper, look arbitrary.
I've been thinking about what the real handover looks like. Not the formal one. The real one.
There are three categories of knowledge that walk out the door when someone leaves:
The documented stuff. Architecture decisions, runbooks, specs. This is the easy part. You can point to it. Someone can read it. Most people think this is the handover. It isn't.
The undocumented stuff that should exist but doesn't. The reason we picked this queue implementation over that one. Why there's a weird conditional buried in the codebase. The edge case that only surfaces under specific load. He knows these. He's been meaning to write them down. He hasn't.
The stuff nobody knows needs to be documented. This is the dangerous category. Knowledge so embedded in how someone thinks about the system that they've stopped noticing it. It doesn't feel like knowledge anymore - it feels like common sense. To the person coming in next, it's invisible.
The third category is what actually bites you. Not the missing docs. The missing mental models.
The new person reads the architecture doc. They understand the components. They start touching things and find that reality is 15 degrees off from the diagram. They ask why. Nobody knows - the person who knew left.
Here's what I've learned actually works:
Document the "why," not just the "what." What the system does is in the code. Why it does it that way - and what alternatives were rejected - is in nobody's head but the person leaving.
Pre-mortem the handover. Imagine the team six months from now, stuck on something. What is it? Write that answer down before the last day.
Pair on the weird stuff, not the obvious stuff. Anyone can read the README. Spend the pairing sessions on the gotchas - the things that aren't written anywhere, that get handled a certain way because of a decision made 18 months ago that nobody else was in the room for.
Leave breadcrumbs in the code. Comments that explain decisions, not just behaviour. Future developers spend more time in the codebase than in the wiki.
The handover doesn't happen on someone's last day. It happens in the weeks before - if you're deliberate about it.
27 days. Enough time to do this right.
TL;DR
- What you lose when someone leaves isn't the documented stuff - it's the mental models nobody knew to write down
- Document the "why" and rejected alternatives, not just the "what"
- Pre-mortem: imagine the team stuck six months from now - write the answer now
- The handover happens in the weeks before the last day, not on it