Handover is a feature

Most software projects end the same way. The features are finished, the demo goes well, and in the final week someone remembers handover. The team that built the system writes a hurried document, records a walkthrough video, and moves on. Three months later, something breaks at an awkward hour and the people now responsible discover that the document describes how the system was meant to work, not how it actually works.

We think handover should be treated as a feature: specified at the start, built throughout, and tested before the project is called done.

01#What a good handover gives you

The aim is that the people who will own the system can run it without calling the people who built it. In practice that means they can do five things on their own:

• →Deploy it. Ship a change to production, and roll it back if needed.
• →Tell whether it is healthy. Know where to look and what normal looks like.
• →Fix the common failures. The handful of things that are most likely to go wrong, and what to do about each.
• →Change the everyday settings. Limits, schedules, email wording, user access, without touching code where possible.
• →Understand why it is the way it is. The important decisions and the reasons behind them, so they don't undo something deliberate by accident.

If any of these depends on a particular person's memory, the handover isn't finished.

02#Why it goes wrong

It is left until the end

At the end of a project, the people with the most knowledge are also the busiest and the most eager to move on. The details that matter most, such as why the import skips certain records or which setting must never be changed on a Friday, are exactly the ones that were obvious during the build and are forgotten when writing the document weeks later.

It is written for the wrong reader

Documentation written by builders tends to describe the architecture: the services, the data model, the clever bits. The person on call at night doesn't need the architecture first. They need "the nightly sync failed; here is how to check why and how to run it again".

It is never tested

A document that nobody has followed is a guess. Commands have typos, steps are missing, access that the author had is assumed. These gaps only appear when someone else tries to use it, and that should not be during an incident.

03#How to build handover in from the start

Put it in the scope

When the project is planned, write the handover requirements next to the features. Name who will own the system, what they need to be able to do, and how you will prove they can. Give it time in the plan. If it isn't in the scope, it will be squeezed out by the last feature.

Write the runbook as you go

Each time the team builds something operational, such as a scheduled job, an integration or an alert, they add its entry to the runbook in the same piece of work: what it does, how to tell if it failed, how to rerun it, who to tell. A feature isn't done until its runbook entry exists. This is a small habit, a few minutes per change, and it removes the end-of-project scramble entirely.

Keep the decisions with the code

A short decision log explains the choices that look strange from outside. It answers most of the "why did they do it this way?" questions before anyone has to ask them.

Automate what you can

The best handover document is one that's partly unnecessary. If deployment is a single command or an automatic step when code is merged, there is nothing to explain. If settings live in an admin screen rather than a configuration file, the owners can change them safely. If health checks run automatically and alert the right person, nobody needs to remember to look. Every manual step you remove is one fewer thing to hand over and one fewer thing to get wrong.

Give the owners access early

The new owners should have their own accounts, permissions and alerts weeks before the project ends, not on the last day. Access problems are among the most common reasons a handover stalls, and they take time to sort out.

04#Test it like any other feature

A feature has an acceptance test. So should handover. A good one is a short exercise, run before the final week:

• →Someone from the owning team, who did not build the system, deploys a small change using only the documentation.
• →The builders deliberately cause one of the common failures in a safe environment, and the owner diagnoses and fixes it from the runbook.
• →The owner changes an everyday setting and confirms the effect.

The builders watch and take notes but don't help. Every time the owner gets stuck, that is a gap in the handover, and it gets fixed. Usually the first run finds several. The second run, a few days later, should be smooth.

05#What it costs, and what it saves

Building handover in from the start typically adds a modest amount of effort across the project, mostly in small runbook updates and one or two practice sessions. Compare that with the cost of a team that can't run its own system: urgent calls to the original builders, changes delayed because nobody dares touch the code, and eventually a rewrite because the system has become a black box.

That is the standard we hold our own work to. It is also a fair question to ask of any supplier before the project starts: how will we know your handover is done, and when will we test it?