Notes on leaving a codebase
Six things I wish I had done before handing over a system I had worked on for four years.
Handing over a system is a skill nobody practices, because by definition you only do it when you are leaving and no longer have time to do it well. Notes from getting it wrong.
Write down the decisions, not the architecture. The architecture is visible in the code. What is invisible is why the queue is between those two services instead of a direct call, and that the answer is a vendor rate limit that no longer exists. Three paragraphs of that is worth thirty pages of diagrams.
Name the things you were afraid of. Every long-lived system has two or three places the maintainer avoids touching. That fear is real information, and it dies with your access badge. Write down which files those are and what you think would happen.
List the recurring failures with their fixes. Not the ones in the runbook, the ones you fixed so often you stopped writing them down. If you have muscle memory for a fix, that is precisely the knowledge that will not survive.
Point at the load-bearing weirdness. The environment variable that must be set before the config loads. The migration that has to run twice. The cron job whose schedule matters for a reason nobody remembers. These are landmines, and you are the only person holding the map.
Say what you would do next, and why you did not. Your successor will spend their first month generating a list of improvements. Most of the items will be things you already considered and rejected for reasons. Handing over that list with the reasoning saves them a quarter.
Do it three months early, in public. The version written in your last week is a document nobody reads. Written early, as commits and comments and design docs while you still care, it becomes part of the codebase instead of an artifact attached to your departure.
