Handing Over a Software Project: Documentation, Access and Knowledge

In most companies, handing over a software project looks like this: the final invoice arrives, accompanied by an email with a link to the repository and a note that everything important is in the README. It works for three weeks. Then comes the first outage outside working hours, or a request for a minor change — and it turns out that the only person with access to the production database no longer works for the supplier, the domain is registered under his personal account, and backups are running but nobody has ever tried to restore one.

Yet a handover is not an administrative step at the end. It is a distinct phase with its own scope, schedule, budget and acceptance criteria. And above all — it can be planned from the start of the project, or improvised in the last week. The difference between those two approaches is paid for by the receiving side, usually at the worst possible moment.

Handover readiness is not a document written at the end. It is a property of the project that either exists continuously or does not exist at all. A team that assumes from day one that someone else will eventually take the system over works differently: it keeps infrastructure as code rather than as a sequence of manual clicks, stores secrets in a secret manager rather than in configuration files on disk, creates third-party accounts under the client's company email addresses rather than personal ones, and records the reasoning behind architectural decisions at the moment the decision is made.

That last point is decisive. Reconstructing eighteen months of decisions in the final week of a project is not documentation but archaeology — and the result is a text that sounds plausible and is one third inaccurate. If you are working through the individual phases of custom software development, the handover belongs in the plan just as much as testing or deployment.

The second thing settled at the beginning is the contract. An exit clause should name exactly what the supplier hands over when the cooperation ends, within what deadline, who owns the accounts and licences, and how many support hours are included in the price. If this is only addressed once the relationship is tense, the client's negotiating position is weak. It belongs among the questions worth asking when choosing a software supplier.

A practical handover checklist has three areas. None of it is exotic, and yet in real handovers at least half of it routinely goes missing.

Code, environments and deployment

The repository including its history, not just the latest snapshot. Alongside it, a description of the branching and release strategy — which branch is the production one, how a release is created, which tag marks the version currently running in production. Then a list of environments (development, staging, production), how they differ from one another and where those differences cause surprises. And finally the deployment procedure and the rollback procedure. Rollback is the part documented least often and needed most urgently.

Access, accounts and licences

The key word is rotation, not sharing. Handing over access does not mean sending the existing password — it means creating new credentials for the receiving side and invalidating the old ones. The same applies to API keys, service accounts, SSH keys and CI tokens. This area also covers infrastructure provider accounts including billing ownership, the domain registrar and DNS management, third-party accounts (payment gateway, email and SMS gateway, mapping and analytics services, monitoring) and licences with their renewal dates. For mobile apps, add app store accounts and signing certificates — without them the app cannot be updated, only republished under a new identity.

Data, operations and knowledge about the system

The database schema and the way it changes (migrations), the retention policy, and above all the backup and restore procedure. Backups can be checked in five minutes; a restore has to be rehearsed. A backup nobody has ever restored should be treated as non-existent until proven otherwise. This area also covers monitoring and alert routing — after the handover there must be a named person whose phone the alert actually reaches. And finally records of architectural decisions, a list of known issues together with their workarounds, and a runbook for the three to five most frequent incidents.

Most handover documentation is written in a single burst of one week, delivered as a PDF, and from that day on it only decays. After six months it is more dangerous than its absence: it presents itself as the source of truth while half the procedures no longer apply, and whoever uses it during an incident loses time in a dead end.

The difference between dead and living documentation is not the quality of the writing but whether the document is used by someone and whether an error in it becomes visible. Three kinds of content work. The first is content that cannot be derived from the code: why a decision was made, which alternatives were considered, which business rule sits behind that odd exception in the order process. The second is content that gets executed — a local environment setup script that also runs in CI, a data seed, infrastructure as code. When it stops being valid, the pipeline breaks. The third is a runbook that is genuinely opened during incidents and amended after each one.

Documentation that retells the code in prose, by contrast, becomes untrue within weeks. A good readiness test is simple: a new developer receives only the documentation, no verbal help, and has to get the project running locally and deploy a trivial change to staging. Whatever stops them is a gap in the documentation. The same logic applies to long-term software maintenance and development after launch — documentation is an operational tool, not an attachment to an invoice.

A typical "knowledge transfer" looks like a series of calls in which the supplier shares a screen and talks. The receiving team nods, takes notes and leaves with the feeling that it understands. A month later, at the first real deployment, it turns out that it does not.

The workable alternative is to reverse the roles. The sessions are working sessions: the receiving team holds the keyboard, the supplier sits alongside and answers questions. The staging deployment is done by the new team. The backup restore is done by the new team. The simulated incident following the runbook is handled by the new team. Three to five ninety-minute sessions, each with a concrete outcome, deliver more than twenty hours of presentations. Recordings of the sessions are a useful supplement, not a substitute.

Knowledge the receiving team has never used with its own hands has not been transferred — it has merely been recorded on video.

Knowledge about the data is a category of its own. In a system that came out of a migration from an older platform, the most valuable information is usually which historical records are inconsistent, why, and how they are handled. That knowledge lives almost exclusively in people's heads and almost never in the repository.

Between "the supplier operates the system" and "the supplier is gone" belongs a transitional period, typically four to eight weeks depending on the complexity of the system. The new team operates, the original one is on standby with an agreed response time and a pre-allocated number of hours. The critical part is defining when to escalate: if the new team calls about every trifle, no knowledge transfers; if it never calls, an outage is being risked.

The handover itself needs acceptance criteria — otherwise it never has a clear end. A sensible set looks like this: the receiving team has independently deployed a change to production; independently performed a backup restore into a test environment; signed in to all third-party accounts and owns them; alerts go to its people; it has resolved at least one real or simulated incident without the supplier stepping in; and all secrets have been rotated. Until those points hold, the handover is still in progress, whenever the final invoice happened to be issued.

The most common cause of failure is not on the handing-over side. It is on the receiving side: nobody has time allocated for the handover. People are one hundred percent assigned to other work, they attend the sessions "if they can", they will read the documentation later, and later never arrives. The result is the same as if the handover had never happened — except that both sides believe it did.

In practice this means three things. A named owner of the handover on the receiving side, not "the IT department". Real capacity, roughly twenty to thirty percent of the time of two or three people during the transitional period. And a clearly designated person who will receive alerts from the first day after standby ends. If a company cannot secure these three things, it is more honest to extend the cooperation with the original supplier than to hand the system over into a void.

There is also a situation in which a handover makes no sense: the system is so entangled with one team's know-how and so poorly documented that taking it over costs more than rewriting the critical part. In that case the handover is more of a controlled wind-down than a transfer of operations. At INTERFASE we handle such situations within custom software development by first stabilising operations and only then deciding the system's further fate.

Handing over a software project is a process, not an email. It is planned from the start, it has its own scope and acceptance criteria, and it ends when the receiving team has independently deployed the system, restored it from a backup and survived an incident. Documentation is worth something only if it is used; access is rotated, not shared; knowledge is transferred through work, not through presentations. And even a perfectly prepared handover does not work if the receiving side fails to assign a named owner and real time.

If you are taking over a system from another supplier, or preparing the handover of your own project and would like to walk through the checklist against a specific case, get in touch with us — we will help define both the scope of the handover and its acceptance criteria.