Handover is part of the product

Sharing the source code and cloud account transfers important assets. It does not transfer the ability to run the system. The client also needs to understand what the platform is doing, perform routine work safely, recognise when something is wrong, and know which changes still require an engineer.

On this engagement, handover was part of the roadmap from the first specification. AG Systems’ founder required the final package to cover the material needed to operate, release, diagnose, and safely change the platform. That commitment stayed in place even though the client engaged AG Systems for ongoing operations and maintenance services from the beginning. Continued support was a service the client chose, not a dependency the delivery created.

With that groundwork in place, the closing stage could concentrate on operator-facing deliverables such as guides, screenshots, alerts, runbooks, and training. It completed an early roadmap commitment rather than inventing a handover after the build was finished. AWS makes the same lifecycle point in its operational-readiness guidance ↗: readiness work begins during design and continues through delivery.

The platform in this engagement has at least three operating roles. An administrator owns catalog content, publishing, settings, and users. An order manager needs payment, fulfilment, refund, and exception state. An inventory manager needs one fast, constrained way to change stock and nothing else.

Those roles shaped the administration console before they shaped any document:

• Navigation and permissions per role, with the API enforcing the same matrix.
• A stock-only save on the product form, so the inventory role can adjust quantity without being able to touch content.
• A publish page whose first line says whether the live site matches current content, with the same badge in the sidebar everywhere.
• Self-service user administration, specified so that adding or deactivating an operator needs no developer and no database session.
• Status explanations written in the language of the workflow: “Changes pending”, “Sold out”, “Needs review”.

When the product already reflects the operating model, the guides get shorter. They describe what to do, not how to work around a generic interface.

The handover package has nine role-scoped guides in Markdown with thirty annotated screenshots. Each guide follows the tasks of its reader, using “how-to guide” in the sense the Diátaxis framework ↗ defines it: what to do, in order, to get a specific thing done. A catalog guide explains which changes take effect immediately and which wait for publication. An order guide follows the commercial states an operator may have to investigate. Neither tours unrelated screens.

The final files are PDFs, but they are not maintained as separate PDF documents. Each one is assembled from versioned sources and reusable instruction blocks. A shared instruction can appear in every guide that needs it, while role-specific material remains scoped to the people who perform that work. Changing the shared source once rebuilds every affected guide, which makes updates cheaper and reduces the chance that two guides give different advice.

The build creates one self-contained guide per role and fails instead of quietly publishing an incomplete package. It checks that source transformations still apply, internal references resolve, required screenshots exist, and the generated files contain a credible result. Because the source has a known structure, the same pipeline can grow checks for missing required sections, unreplaced placeholders, inconsistent terminology, or accessibility metadata without changing how the guides are written.

This is the docs-as-code approach ↗ applied to an operator handover: version history, review, a repeatable build, and automated checks. The guides receive the same attention to change safety as the software they describe.

Monitoring is useful only if its recipient can turn a signal into an action. The useful categories start with the service experience, not an inventory of internal components. Google’s four golden signals ↗, latency, traffic, errors, and saturation, provide a useful base. A particular system may also need availability, freshness, or completion signals for its important workflows.

• AvailabilityCan users reach the journeys the service exists to provide?
• LatencyAre important interactions staying within their operating budget?
• ErrorsAre requests or background operations failing at a meaningful rate?
• TrafficHas demand changed enough to alter how the other signals should be read?
• SaturationIs a constrained resource approaching the point of degradation?
• FreshnessDoes published or synchronized data reflect the expected state?
• CompletionAre important asynchronous workflows finishing when expected?

The applicable set depends on the system, and not every measured signal deserves an alert. Thresholds also need enough traffic to mean something. One failed request during a quiet period may be a 100% error rate without being a useful reason to interrupt someone.

Each actionable alert should carry a stable link to the relevant runbook entry. That entry starts with an identity and scope check, then provides the dashboard or log query to inspect, likely benign causes, a safe recovery step, and an escalation boundary. Planned tests or maintenance that may trigger the signal belong there too, so expected behavior is not mistaken for an incident.

The link is part of the alert’s contract and needs the same review as its threshold. A rename can otherwise leave the signal working while its response path breaks. Google’s SRE workbook expects a playbook entry per alert ↗ and recommends that alerts be immediately actionable.

The release process was documented before the first production release. It supports short release cycles, several types of pre-production environment, and one production environment. The path is automated, but production remains a deliberate decision: an authorized person chooses when a tested release crosses that boundary.

• Short release cyclesSmall changes move through one repeatable path.
• Purpose-specific pre-productionDifferent environment types support development, acceptance, and focused testing.
• One production boundaryA deliberate human decision promotes a tested release into production.
• Auditable historyThe running release can be traced to its source change and deployment record.

The Git history records that release history, so the running version can be traced back to the change that produced it. Frequent, smaller releases keep that history useful: when something changes in production, the set of possible causes remains narrow. These principles are widely adopted across the industry. Google’s release-engineering guidance ↗ describes frequent releases, auditable change reports, and independent testing environments at Google scale. The GOV.UK’s deployment guidance ↗ applies the same ideas to public services: release little and often, keep deployments auditable, and use appropriate pre-production environments.

The infrastructure follows the same model. It is defined as code using reusable building blocks and explicit configuration for each environment type. Capacity, integrations, and other settings may vary between environments without turning any one of them into a collection of undocumented console changes. A proposed infrastructure change can be reviewed before it is applied.

None of this makes infrastructure change non-technical. It makes the change inspectable. The client received a system whose production history is represented by reviewed source changes, release records, and infrastructure plans rather than an undocumented cloud account.

Written material cannot replace a transfer session. Training connected the guides and the system’s behavior to the client’s actual responsibilities. Operators worked through representative tasks with the material in front of them, and their questions became useful tests of whether the interface, instructions, and engineering boundary were clear enough.

The engagement closed with training completed, a signed handover document, and operational ownership transferred to the client. The finish line was the client operating the live platform, not the application being deployed.

Naming the boundary in the handover document is as important as the guides themselves. A successor who knows which decisions are theirs and which need an engineer can plan the second kind instead of discovering them under pressure.

The practical acceptance test is whether the new owner can complete routine work, make the first safe decision when a signal arrives, follow the documented release path, and recognise when to escalate. Passing that test transfers operating capability, not just files.

This work costs time during delivery and produces material that has to stay current. For a prototype that will be thrown away, a narrower handover is right. For software that will run for years under someone else’s ownership, postponing it usually costs more: the team has to reconstruct the operating model after the people who held it have moved on.

Inspect the completed handover in the engagement record →