Business owners who have been through a difficult change of software vendor tell similar stories: the original developer moved on, the code was on their laptop, the server password was unknown, nobody understood how the system was deployed, and the new team spent months rediscovering how everything worked before they could make a single change. All of it was avoidable. The time to prevent lock-in is at the start of a project, by agreeing what documentation and handover you will receive — and checking that you receive it.
This guide lists what to ask for, why each item matters and how to check it without being a developer.
Principle: another team should be able to take over
The test for good documentation and handover is simple: could a competent, unfamiliar development team take over your system — understand it, run it, change it and deploy it — without help from the original developers? You may never need to change partners. But if another team could take over, you have real ownership and real choice, and your current partner's work is likely to be well organised.
1. Source code and repository
- Ownership. The contract states that code and intellectual property created for you belong to you on payment. Reused components owned by the developer are licensed to you perpetually for your use.
- Repository access. The code is kept in a version-controlled repository in an account your business owns or can take over, with your own access throughout the project — not delivered as a zip file at the end.
- Complete code. Everything needed: web application, mobile apps, back-end services, database migration scripts, configuration templates and automated tests.
- History. The version history shows changes over time; it helps future developers understand why code is the way it is.
How to check: log in to the repository yourself and see recent activity. Ask the team to show you where each part of the system lives.
2. Account ownership
Software depends on many accounts: hosting, domains, DNS, email and SMS services, messaging APIs, payment gateways, app store developer accounts, maps and other third-party services, monitoring and error tracking. Each should be registered to your business, with billing in your name and at least two people in your company holding owner access. Developers get their own access, granted and revocable by you.
Keep an account register: service, purpose, owner, renewal date, who has access. Review it at handover and whenever people leave.
3. Architecture overview
A short document — often a few pages with a diagram — explaining:
- The main components (web app, API, mobile apps, database, background jobs, file storage).
- How they connect, and which external services they use.
- Where everything is hosted.
- Key technologies and versions.
- How data flows for the main processes.
This is the map a new developer reads first.
4. Decision records
Important choices — why a particular framework was chosen, why offline sync works a certain way, why a report uses a summary table — should be recorded briefly with their reasons. Decision records stop future teams from undoing sensible decisions out of ignorance, or from preserving bad ones out of caution.
5. Setup and deployment guide
- How to set up a development environment from scratch.
- How configuration and secrets are managed (never stored in the code itself).
- How releases are built, tested and deployed to staging and production.
- How mobile apps are built, signed and published to app stores.
- How database changes are applied safely.
- How to roll back a bad release.
Ideally, deployment is automated, so the guide mostly explains how to use the automation.
How to check: ask a developer who did not build the system — perhaps someone from the partner's other team — to set it up from the guide. Gaps appear quickly.
6. Operations runbook
Practical instructions for running the system: monitoring and alerts, backup schedule and how to restore, routine maintenance, scheduled jobs and what to do if they fail, common problems and their fixes, and contacts for third-party services. This is what someone reaches for at 9 pm when something is wrong.
7. Data documentation
A description of the main data entities — customers, orders, jobs, assets, items — their important fields and relationships, and any non-obvious rules (for example, how stock is calculated, or which status values mean what). This helps with reporting, integrations, migrations and future changes.
8. Integration documentation
For each integration: what data moves, in which direction, how often, how errors are handled, where logs are kept and which credentials are used. If the system provides its own API for others, document the endpoints for future integrators.
9. User and administrator guides
Users need short, task-based guides by role: how a coordinator creates and assigns a job, how a technician closes it, how accounts raises an invoice. Quick reference sheets and short videos often work better than long manuals. Administrators need guides for managing users and roles, settings, templates, master data and routine admin tasks.
10. Known issues and backlog
At handover, receive a list of known issues, their severity and workarounds, and the backlog of planned improvements and technical debt. This prevents surprises and gives continuity to future work.
Keep documentation alive
Documentation written once at the end and never updated soon becomes misleading. Better practice is to keep it in the repository alongside the code, update it as part of each change, and review it at major releases. Concise, current documents beat large, outdated ones.
The handover checklist
| Item | Received | Checked |
|---|---|---|
| Contract confirms code and IP ownership | ||
| Repository in company-controlled account, with access | ||
| All accounts registered to the company; account register | ||
| Architecture overview with diagram | ||
| Decision records for major choices | ||
| Setup and deployment guide (tested by someone else) | ||
| Operations runbook, including backup restore steps | ||
| Data and integration documentation | ||
| User guides by role and administrator guide | ||
| Known issues and improvement backlog | ||
| Credentials transferred securely; old access reviewed |
Handover when changing partners
If you do change development partners, plan an overlap: the outgoing team walks the incoming team through the system, deployment and open issues, ideally over a few weeks. The incoming team should set up the system independently from the documentation, deploy a small change to production and confirm they have every credential before the outgoing team's access is removed. Treat it as a project with its own checklist, not a single meeting.
Example
A manufacturer had its production tracking system built by a small firm that later closed. The code was in the firm's repository account, the server was in its hosting account and the mobile app was published under its developer account. Recovering access took months; the app had to be republished under a new account, forcing every operator to reinstall it. For its next system, the company required a repository in its own account from day one, hosting and app store accounts in the company's name, an architecture overview, a deployment guide tested by a second developer and a quarterly review of the account register. When the company later brought development in-house, the transition took weeks, not months.
Summary
Documentation and handover determine whether you truly own your software. Secure code ownership and repository access from the start, keep every account in your company's name, and require an architecture overview, decision records, setup and deployment guides, an operations runbook, data and integration documentation, role-based user guides and a known-issues list. Keep documents current, test them with someone new, and you will never be locked in.
Mobile apps need extra care
Mobile apps add handover items that are easy to miss. The app store developer accounts must belong to your business — moving an app between accounts can be complicated, and republishing under a new account forces every user to reinstall. Signing keys and certificates used to publish updates must be stored securely and handed over; losing them can make it impossible to update the existing app. Push notification credentials, app store listings, privacy declarations and the build configuration should all be documented. Ask for these explicitly; they are rarely included unless someone insists.
Handing over credentials safely
Credentials should never be sent by email, chat or spreadsheet. Use a password manager shared within your company, or a secure vault for application secrets, and transfer access by adding your people as owners rather than sharing passwords. After handover, rotate the most sensitive credentials — hosting owner accounts, database passwords, API keys — and remove access for anyone who no longer needs it. Record what was changed and when.
Documentation as part of the contract
Documentation is easy to deprioritise when deadlines approach, so make it part of the agreement. List the documents you expect, when they should be delivered (for example, architecture overview after design, deployment guide before first production release, user guides before training) and include them in acceptance criteria for milestones. Ask for documentation to be updated with every significant release during support. When documentation is a deliverable with a date, it gets done; when it is a vague expectation, it usually does not.
A quick self-assessment
If you already run custom software, answer these questions today: Can two people in your company log in to the hosting, domain and app store accounts? Do you know where the code is and can you see it? Could you restore yesterday's data, and when was that last tested? Is there a document explaining how the system is deployed? If a key developer left tomorrow, how long would it take someone else to make a small change safely? Any "no" or "not sure" is worth fixing now, while everything is working and people are available to help.
Frequently asked questions
Who should own the source code of our custom software?
Your business, on payment as agreed in the contract. Ownership should be written explicitly, together with your right to access the code at any time and to have other developers work on it.
How much documentation is enough?
Enough that a competent new team could understand, run, change and deploy the system without the original developers. That usually means concise, current documents rather than large volumes written once and never updated.
When should we receive the code — only at the end?
No. You should have access to the code repository throughout the project, with the code stored in an account your business controls or can take over at any time.
What if our developer leaves without documentation?
A new team can usually recover by reading the code, setting up the system and documenting as they go, but it takes time and carries risk. Requiring documentation and access from the start prevents this.
Do user guides need to be long manuals?
No. Short, task-based guides, quick reference sheets and brief videos for each role are more useful than a long manual nobody reads.
