Four pages

Four pages, in a file called handover.md, in the root of a repo I picked up in June from a developer who’d left the agency back in March. I had a small change reviewed and live the same afternoon.

I’ve been doing this for 9 years and I can think of 2 other times that’s happened. I spent most of that first morning faintly suspicious of the file, the way you are when a used car is too clean.

I keep turning over which parts of it did the actual work, because they weren’t the parts I’d have guessed.

The setup instructions were the least of it

Running it locally took up maybe half a page. I’d have worked that out on my own inside an hour of poking at it, the way everybody does. That’s a README’s job and I already wrote a whole post about READMEs, so I won’t relitigate it. Same goes for who owns which account, which I went on about at length in 2017.

The rest of it I could not have gotten anywhere, at any price, once that person was gone.

The dates were about 8 lines and they’re the highest-value thing in the whole document. Domain renewal, certificate expiry, the runtime’s security support ending in about a year, the accessibility review, when the contract comes up for a look. That list is the entire difference between a maintenance relationship that looks like foresight and one that looks like a run of emergencies.

The people were described honestly, which I don’t think I’ve ever seen written down before. Not a list of email addresses. Who actually decides things, which is reliably not whoever the org chart nominates. Who has the DNS login and doesn’t know they have it. Which vendor’s support desk is a black hole and which one has somebody who’ll fix it within the hour if you call instead of emailing.

Then the weird stuff that’s weird on purpose. A redirect that exists because of a print run of flyers. A hardcoded value holding up something nobody wants to touch. If that isn’t written down anywhere then it gets cleaned up, and the cleanup is the incident. It’s the same thing I was circling with rewrite proposals, where undocumented behavior looks exactly like cruft to a person who wasn’t there for it.

And how a change actually gets live, human steps included, because “the marketing manager signs off on copy and they’re only in two days a week” is not in any pipeline config.

Written on the way out means written never

I think the word “offboarding” is doing real damage here, because it files the whole activity under the last week, and the document written in the last week does not exist. Two reasons, and they compound.

(1) By then you can’t see it anymore. Everything awkward about the project has been absorbed into your hands. You genuinely cannot remember that the build wants an environment variable that isn’t in any example file, because you set it 18 months ago and your shell has quietly remembered it for you ever since. That’s the same blindness that eats READMEs and it’s at its worst right at the end.

(2) There’s no money and no attention left. The budget is spent, everyone is looking at the next thing, and whatever goodwill remains is being rationed. Nobody is approving 3 days of documentation at that particular moment, and if you’re leaving a job instead of a project you have about a week, an exit interview and a farewell cake.

So the only document that ever exists is the one somebody was already keeping.

“Things I’d have fixed with another month”

That was a real heading in the file, with 6 bullets under it, plainly written, no defensiveness: the known issues, the part held together with tape, a test that had been skipped since February, a dependency 2 major versions behind that’s going to be a project when it finally moves.

That’s the hardest thing anybody has to write in one of these and the difficulty isn’t technical at all. It feels like publishing a list of your own failures, which is uncomfortable in the ordinary case and considerably worse when you’re on your way out and would like to be remembered fondly.

It’s also, by a distance, the most useful part of the document to whoever picks it up. Every one of those 6 bullets is something I’d otherwise have found out in production, at speed, with a client on the phone, quietly forming an unflattering theory about my predecessor.

Instead I thought better of them for it, which I suspect is the exact opposite of what they were worried about.

The part everybody knows and nobody says

Doing this well makes you easier to replace.

Some people keep things in their heads on purpose. Not many, and it’s rarely malicious, and it’s usually a form of insurance. I understand the impulse completely (and I say that as somebody who has absolutely been the person holding a project together from memory!), especially for a contractor whose next month depends on this month going well.

I still think it’s a bad bet, and not for noble reasons.

A bus factor of 1 is job security at best and a cage at worst. You can’t be moved off the project. You can’t be promoted past it, you can’t take two weeks in August without your phone, and you get to be the person who’s called on Christmas Eve. Every bit of value you’ve built up is locked inside one client relationship that’s going to end anyway, on a schedule somebody else controls.

And being recommended is what actually generates work. Nearly every good project I’ve had in 9 years came from somebody saying my name in a room I wasn’t in, and “they left everything in good order” is a much more repeatable sentence than “only they understand it,” which people tend to say with a slight wince.

Give it to a stranger

Same test as a README, and almost nobody runs it. Hand the document to somebody else and have them do one real task with it without asking you anything. Not a thought experiment. An actual small change, actually deployed.

Everything they have to come ask you about is a gap, and the gaps are never the ones you’d expect, because they’re the things you know so well it never occurred to you they were things.

It’s half an hour of somebody else’s time, once a year, and as far as I can tell it’s the only way to find out whether four pages of confident documentation are true.

Mine’s mostly empty right now

I start the file on day one now. It’s headings and white space for the first couple of months and I fill it in as I go, usually right after I’ve lost an hour rediscovering something I’d have sworn I’d remember. After that it’s 10 minutes a quarter, plus whatever changes when a date or a person changes.

Which is close to what I said about READMEs 7 years ago, so either I have one decent idea that keeps applying, or I have one idea and I keep finding new places to put it. I’m honestly not sure which lol The file has already saved me twice this year though, both times from something I’d written down myself and completely forgotten. So I’ve stopped worrying about it either way.