The offboarding document
Written at the end means written never. And doing it well makes you easier to replace.
In June I inherited a client project from a developer who had left the agency in March. There was a file in the repo called handover.md. It was four pages. It told me how to run it, where it deploys to, which of the client’s people decides things, what the odd bits were and why, what was deliberately unfinished, and that the platform’s security support ends in about a year.
I was productive on that project on day one. I have been doing this for ten years and I can think of two other times that’s happened.
Written at the end is written never
The word “offboarding” makes this sound like something that happens when you leave, and that’s the mistake. A document written at the end of a project doesn’t exist, for two reasons that compound.
The first is the one I’ve written about before with READMEs: at the end you can no longer see what’s confusing. Everything awkward about the project has been absorbed into your hands. You genuinely cannot remember that the build needs an environment variable that isn’t in any example file, because you set it 18 months ago and your shell has remembered it ever since.
The second is money. The end of a project is the moment when the budget is spent, the attention has moved to the next thing, and any remaining goodwill is being carefully rationed. Nobody is going to authorize three days for documentation at that point, and if you’re leaving a job you have about four days and a farewell party.
So the only version that exists is the one that was already being maintained.
The end of a project is when the budget is gone, the attention has moved, and you can no longer see what's confusing about your own work. It's the worst possible time to write any of this down.
What goes in it that isn’t in the README
A README says how to run the thing. An ownership list says who holds the accounts. I wrote about both of those in 2017 and they’re necessary and they’re not this.
This is for the next person doing your job, and it’s the things that live in your head.
Why, for each significant decision. Why this platform, why this hosting company, why the payments are handled the way they are. Not to justify them, to prevent them being undone by somebody who reasonably assumes there wasn’t a reason.
The people, described honestly. Not a list of email addresses. Who actually decides things, which is usually not the person on the org chart. Who to ask about content. Who has the DNS login and doesn’t know they have it. Which supplier’s support desk is useless and which one has a person called Dave who will fix things if you ring rather than email.
The dates. Domain renewals, certificate expiry, the runtime’s end-of-support date, the contract review, the annual accessibility check. This is the highest-value section in the whole document and it’s the one that makes a maintenance relationship look like foresight rather than emergencies.
The deliberate weirdness. The redirect that exists because of the leaflets. The hardcoded value that’s holding everything up. Anything that looks like a mistake and isn’t. If these aren’t written down, they get tidied up, and the tidying is the incident.
How a change actually gets live. Branch, review, approval, deploy, verification. Including the human steps, because “the client’s marketing manager has to approve copy changes and they’re part-time on Thursdays” is not in any pipeline configuration.
The section nobody writes
What isn’t done.
The known issues. The bit that’s held together with tape. The test that’s been skipped since February. The feature that works but only for the happy path. The dependency that’s two major versions behind and will be a project when it moves.
This is the hardest section to write, and not for technical reasons. Writing it feels like publishing a list of your own failures, particularly if you’re leaving, and particularly if you’re leaving on good terms and would like to be remembered fondly.
It’s also, by a distance, the most useful part of the document to the person who picks it up. Every one of those items is a thing I would otherwise discover in production, at speed, with a client on the phone, forming an unflattering theory about my predecessor.
The developer whose document I inherited in June had a heading called “things I’d have fixed with another month.” Six bullet points, plainly written, no defensiveness. I thought considerably better of them for it, which is the opposite of what they presumably feared.
The awkward bit
Doing this well makes you easier to replace. Everybody knows it and nobody says it, and I’d rather say it.
Some people, not many but some, keep things in their heads deliberately. It’s rarely malicious and it’s usually a form of insurance, and I understand the impulse completely, especially for a contractor whose next month depends on this month.
I think it’s a bad strategy, and not for noble reasons.
Being irreplaceable on a project means you cannot be moved off it. You can’t be promoted past it, you can’t take two weeks in August without your phone, and you become the person who is rung on Boxing Day. Every scrap of value you’ve accumulated is locked in one client relationship that will end anyway, on somebody else’s schedule.
And the actual thing that generates work is being recommended. In ten years, almost every good project I’ve had 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 recommendation than “only they understand it,” which is a thing people say with a slight wince.
Test it while you’re still there
The same test as a README, and almost nobody runs it.
Give the document to somebody else and have them do one real task with it, without asking you anything. Not a hypothetical. An actual small change, deployed.
Everything they have to ask you is a gap, and the gaps are always in the places you’d never have guessed, because those are precisely the things you know so well you didn’t think to write them.
20 minutes of somebody else’s time, once a year, and it’s the only way to find out whether four pages of confident documentation actually work.
One idea, new places to put it
Ten minutes a quarter, in a file in the repo, updated whenever something on the list changes.
I’ve started writing mine on day one now, as a mostly-empty file with the headings in, and filling it in as I learn things. Which is exactly what I said about READMEs seven years ago, so I appear to have one idea and I keep finding new places to put it.