Helper CTO Series 17 | Don't Let Handover Become a Black Box: A Minimal Documentation Set to Leave Behind

"Documentation? He said when he left that it's all in the code." That line has a cost, and it shows up in the first week the next engineer starts: they spend three days guessing how the system actually runs, and if something breaks during those three days, nobody is capable of fixing it. You don't undervalue documentation — nobody ever told you the minimum you actually need. Here are the following five things, each one page or less.

Without documentation, a handover means starting from archaeology

"Archaeology" means the new person spends days guessing how the system runs, testing as they guess, and you pay for every mistake. What they have to guess includes:

• Which platform the server is on, which account to log in with, and who pays the monthly bill.
• Who the domain is registered under, when it expires, and who is responsible for renewing it.
• Where the database password is stored, and whether backups are actually running.
• Whether deployment is manual or automatic, and when the last successful deploy happened.
• Which third-party services are still being charged, and which ones nobody actually uses anymore.

Worse, some things simply can't be guessed: deployment commands sitting on the old engineer's laptop, login methods only they knew. If they weren't written down, they're gone.

The minimal documentation set: five things, one page each

You don't need a technical spec binder — nobody ever maintains those. You need five pages that let an engineer who's never seen this system get up to speed in a day:

All five together shouldn't run more than five pages. Remember, this is written for "the engineer who starts tomorrow," not as a note to yourself.

Which two to write first

If you can't write all five at once, start with these two — the other three can be filled in later:

• How to deploy: If only one person can currently do this, it's the most fragile point in the whole system. Write down the steps: where to pull the code from, what to run, how to confirm it worked, and how to roll back to the previous version if it fails.
• Who can log in: If account access has never been sorted out, people who've left may still be able to get in. This page only needs to say "where to get the password" — the passwords themselves belong in a password manager.
• Both of these can be written without a meeting: one page each, a first draft in an afternoon, with the other three filled in later.

"Getting things back" and "writing things down" are two things you need to do together — the 12 things to get back first after an engineer leaves covers the former. In the first month after we take over a system (see what we do in the first month after taking over), the "current-state map" we produce in week one is the first draft of these five pages.

How to keep it from going stale

Documentation's biggest enemy isn't never being written — it's being written and then never updated, until six months later it no longer matches reality and actively misleads the next person. Three practices:

• Update it alongside the change: Every time you switch hosts, add a service, or change how you deploy, update that page as part of the same change.
• Review it every quarter: Tie it to your security updates. Security updates happen at least once a quarter — go through the five pages while you're at it.
• Keep it somewhere everyone can find it: alongside the code, or in a shared company space. Sitting on one person's personal drive is the same as not existing.

Telling whether documentation is still alive is simple: ask yourself, "If the person responsible took a week off, could someone else keep the system running using these five pages?" If the answer is no, it's time to update them.

Why we hand these over when our engagement ends

Many vendors don't leave documentation behind, and the reason, if you said it out loud, sounds bad: the less documentation, the harder it is for the customer to leave. We do the opposite, for a practical reason:

• We bill monthly, and you can stop anytime — a model that relies on "you can't leave" doesn't hold up.
• There's only one thing we can rely on: you feeling, every month, that the money was well spent.
• Leaving the documentation with you is what gives you a choice; and if you stay after having that choice, that's a real partnership.

For the other details a handover needs to cover, the system operations handover guide has the full checklist.

The five pages Nerdtechnic hands you

• All five written in the first month: we produce a first draft in the first week after taking over, not something we scramble to fill in when the engagement ends.
• Updated with every change: switch hosts, add a service, change how you deploy — the corresponding page gets updated the same day.
• Reviewed quarterly alongside security updates: at least once a quarter, we check all five pages against reality.
• All of it stays with you when we're done: the documentation and records are yours, so a handover never turns into a black box.

The value of documentation isn't how polished it looks — it's whether you can swap people in at any time.

Keeping a handover from turning into a black box doesn't take a thick manual — it takes five pages that someone actually keeps updated. Nerdtechnic takes over your system as your Helper CTO, writing these five pages in the first month and maintaining them alongside every change after that. The first step is a 60-minute system health check: we just need visibility into the code, no production credentials required, and you'll get a one-page report you can understand within 3–5 business days. If your system today is still "all in the code," let us help you write the first page: Helper CTO: System Maintenance Plan.