What we put in a handover pack

Lock-in is rarely a decision anybody makes. It is what happens by default when the only complete description of a system lives in the heads of the people who built it. You do not notice until you want to change supplier, or hire in-house, or simply understand what you are paying to maintain.

The handover pack is the deliberate opposite of that, and we treat it as part of the build rather than as paperwork at the end. It has one acceptance test, and it is unforgiving: give it to an engineer who was not on the project and see whether they can operate the system without a meeting.

What is in it

• Architecture notes with the reasons. Not just what the components are, but why they were chosen and what was rejected. A future engineer who does not know why you avoided a queue will add one, and rediscover your problem the expensive way.

• Environment setup, tested from zero. The exact steps to get the system running on a clean machine, written by following them on a clean machine. Documentation written from memory is always missing the step the author has already done.

• Runbooks for the things that actually break. Not a generic troubleshooting section. The specific failures this system has: the integration that times out, the job that needs re-running after a failed night, the queue that backs up when an upstream provider is slow. Each with symptoms, cause and the fix.

• Secret inventory and rotation procedure. Every credential the system holds, where it lives, what it grants, and the steps to rotate it. This one is regularly the difference between an incident and a crisis.

• Data model and its edge cases. The schema, plus the fields whose meaning is not obvious and the historical rows that break the current rules. Every real system has some.

• Deployment and rollback. How a change goes out, how you know it worked, and how you put it back when it did not. Rollback is the half people skip, and it is the half you need at eleven at night.

• Monitoring and alerts. What is watched, what fires, who it goes to, and what a given alert actually means. An alert nobody can interpret is noise that trains people to ignore the next one.

• Access and ownership. Which accounts, domains, repositories and cloud resources are involved and whose name they are in. Ours are transferred to you; that is the point.

A handover pack that only makes sense to the person who wrote it is not a handover pack. It is a diary.

Why we write it during, not after

Documentation written in the last week of a project is written by tired people from memory, and it shows. Written as the work happens, it costs almost nothing extra because the details are still in front of whoever is doing the work — and it has a second benefit: writing down why a decision was taken tends to expose the decisions that were not really taken at all.

The test, run properly

Before a project closes, someone from our team who did not work on it takes the pack and sets the system up from scratch. Every question they have to ask is a gap, and every gap gets written in before the pack is handed over. It is a couple of hours of somebody senior, and it is the only way to know the document works, because the authors cannot see their own assumptions.

What this means commercially

It means you can leave. If you want to take the system in-house, or move it to another supplier, everything needed to do that is already in your hands and you do not have to ask us for it or pay for a transition project.

That sounds like a strange thing for a supplier to build deliberately. In practice, clients who know they can leave tend to stay, because the relationship continues on whether the work is good rather than on whether leaving is painful. We would rather compete on the first thing.

If you already have a system without one

Inheriting undocumented software is common, and it is fixable. We reverse-engineer the pack from the running system and the code: architecture, runbooks, secrets, deployment. It is bounded work, usually a couple of weeks, and it typically also surfaces two or three risks nobody knew were there — an expired certificate, a credential in source control, a backup that has not run since spring.

handoverdeliverydocumentation Share thisLinkedInWhatsAppEmail

Copy link If you have inherited a system with no documentation and need this produced retrospectively, we do that as a standalone engagement, including for software somebody else built.