How should documentation and handover be specified so source code is not the only deliverable?
Do not let the contract say only “source code will be delivered.” Attach an acceptance checklist covering code and artifacts, data, accounts, configuration and secrets, architecture and APIs, deployment and operations, tests, and third-party licences. Before final payment, the client or replacement team should build, deploy, restore a backup, and complete the core workflow.
Source is only one system asset. Without databases, object files, environment configuration, certificates, third-party accounts, deployment automation, and business rules, a repository may not run. Successful handover means someone who did not build the product can restore it in the agreed environment and operate its core functions from the supplied material.
When agreeing deliverables, handover, and ownership boundaries, also compare Can our system still be maintained if the supplier closes or its core team disbands?; the linked guidance adds context that should be considered in the same decision.
Minimum handover inventory
| Category | Minimum content | Acceptance action | Common omission |
|---|---|---|---|
| Code and artifacts | Complete repositories, branches/tags, lockfiles, builds, licence inventory | Build a named version in a clean environment | Zip only, missing history or private packages |
| Data | Schema, dictionary, migrations, backups, file structure | Restore sanitized data and reconcile core records | Database supplied without object storage |
| Accounts | Ownership and administrators for cloud, domains, certificates, stores, payments, SMS, and email | Client signs in, checks access, and rotates credentials | Resource remains in a supplier's personal account |
| Architecture and APIs | Diagram, service inventory, APIs, callbacks, errors, external dependencies | Exercise critical integrations and failure paths | Online-only API page disappears after service ends |
| Deployment and operations | Environments, configuration, pipeline, release, rollback, monitoring, backup, incidents | Deploy, roll back, restore, and trigger an alert | Secrets in chat and unwritten operating steps |
| Product and tests | Requirements or prototype, role matrix, rules, tests, known issues | Run core UAT scenarios | Screenshots without states or rules |
Make the contract testable
The statement of work or annex names each deliverable, format, version, date, approver, and pass condition. It distinguishes client-owned custom code, third-party assets, and pre-existing Wavesteam components and states the rights to use, modify, and redistribute each. Commercial SDKs, open-source licences, subscriptions, and renewal owners are listed. Phrases such as “all relevant documentation” are not measurable substitutes.
Accounts should normally be opened under the client's organization from initiation, with supplier subaccounts. Temporary provider hosting needs a migration date, export method, fee, downtime, deletion, and exit assistance. Secrets travel through a password manager or secure channel rather than ordinary documents or messages and are rotated after handover.
Pre-handover begins before release or at a milestone with draft documentation and a gap review. Formal handover includes an architecture, release, monitoring, recovery, and incident walkthrough in which the client's technical staff operate the system. The warranty period addresses in-scope defects and handover questions and updates the documentation. New features, environment migration, and long-term managed operations are separate services.
Prove transfer with an exercise
In an isolated but production-like environment, the client or an uninvolved person checks out a named tag, prepares configuration, builds and deploys, restores sanitized data, runs the core workflow, triggers an alert, rolls back an application release, and restores data. Record elapsed time, failures, and missing artifacts and repeat after remediation. If the client has no technical staff, an appointed third party or guided remote exercise with recording is better than a verbal developer presentation.
| Result | Assessment |
|---|---|
| Only the original developer can run it on the original machine | Not transferable |
| New environment works but data or external integrations are missing | Partial delivery |
| Client can deploy, restore, monitor, and complete core work | Technical takeover baseline met |
| Incident exercises and extension notes are also included | Better suited to independent long-term maintenance |
Wavesteam scales documentation depth to the product but keeps account ownership, reproducible code, data recovery, and deployment instructions as baselines. Our Transparent Delivery Standard makes these asset boundaries public; a simple website and a complex payment or IoT platform do not require identical document volume.
References
- NIST SSDF SP 800-218 provides context for protected software, release evidence, and vulnerability response.
- The OpenAPI Specification structures API descriptions but does not replace business rules and failure procedures.
- The Wavesteam Transparent Delivery Standard states our public source, data, deployment, and handover principles.
The signed agreement controls intellectual-property, licence, and warranty duties and may require legal review.