The handover document
On the document we deliver at the end of every engagement — what it contains, why it takes a week to write, and why it is the most expensive single artefact the studio produces.
At the end of every engagement we deliver a handover document. The document is between eighteen and forty pages. It is written from the first day of the engagement to the last. The week of work to finish the document is built into every quote.
The document contains six things, in this order.
One. An overview of what was built and why. Not the marketing pitch — the actual scope, with what was in, what was out, and what was explicitly deferred to a later engagement. We list deferred work because the team that inherits the project will otherwise rediscover it.
Two. The architecture decisions, with the reasoning. We explain what we chose, what we considered and rejected, and under what circumstances the decision should be revisited. The reasoning matters more than the decision. A future team will probably revisit the decision; if they understand the reasoning, they will revisit it well.
Three. The component inventory. Every reusable component, what it is for, what it accepts as props, what it does not handle, and a screenshot. Junior engineers should be able to use the component library after reading the inventory. They almost always can.
Four. The operational runbook. How to deploy. How to roll back. How to add a new environment. How to rotate secrets. How to interpret the monitoring dashboards. What to do at three in the morning when something is broken. This section is the longest. It is also the section that gets read the most often, six months after handover, when the on-call engineer wakes up to a page.
Five. The known issues. Every project has known issues. We list them. Nothing is hidden. If there is a piece of technical debt we decided to ship with, it is in the document with a note about why we shipped with it and what the conditions are for paying it down.
Six. The next twelve months. What we would do next if the budget reappeared. What metrics to watch. What experiments to run. What might break. What to expect at scale. This section is, in some ways, the most valuable. It is also the most likely to be wrong, because the future is hard.
The document is expensive. A full week of senior time goes into it. We charge for the week as if it were any other week, because it is. We do not discount the handover document because the handover document is the most important deliverable of the engagement. It is what the project becomes after we leave. Without it, the project is a black box. With it, the project is a working tool that the inheriting team understands.
We deliver the document at a live readout, walking through every page with whoever will own the project next. We answer questions. We make small corrections. We hand over a paper copy and a PDF. Then we leave.
The handover document is the single most expensive artefact the studio produces. It is also the reason our work survives our involvement.