Fast. Simple. No meetings. No delays.
Home / Blog / Denmark / Documentation and Handover: Avoiding Software Vendor Lock-In

Documentation and Handover: Avoiding Software Vendor Lock-In

What a proper handover contains — source, database, environments, runbooks — and how to write it into the contract.

Cover graphic for the article: Documentation and Handover: Avoiding Software Vendor Lock-In

Good software handover documentation lets another competent team run, deploy and change your system using only what you hold: the source code, the database and its schema, every environment and credential, runbooks for deployment and recovery, and short notes explaining the architecture and key decisions. Write these into the contract as deliverables, not goodwill.

What lock-in looks like

Vendor lock-in is rarely a trap set on purpose. It builds up through convenience: the supplier hosts everything in their own account, deploys from their own laptop, and keeps knowledge in their heads. Everything works until you want to change supplier, bring development in-house, or the supplier is unavailable. Then you discover how much you do not hold.

Warning signs include:

  • The code lives only in the supplier's repository account, or you have never seen it.
  • Hosting, domain, email service or payment accounts are registered in the supplier's name.
  • Deployment is a manual process only one person knows.
  • The system depends on a proprietary framework or licence that only the supplier can use.
  • Questions about how something works are answered with a quote for investigation rather than a document.

The aim is not to distrust your supplier, but to make the relationship a choice. Good suppliers are comfortable with this, and strong handover practice also benefits them, because fewer questions land on one person. If you are still choosing a supplier, see choosing a software development partner for the wider criteria.

The handover pack

Think of the handover pack as a box you could hand to a new team on Monday morning. Define its contents up front, then check them off.

ItemWhat to expect
Source codeComplete repository with history, in an account you control; build and run instructions
DatabaseSchema, migrations, a description of key tables, and a restorable backup
ConfigurationList of settings and environment variables, with sample values and no real secrets in the code
Dependencies and licencesList of libraries and third-party services, with their licence terms
InfrastructureHosting setup description, ideally as scripts or configuration files that can recreate it
RunbooksStep-by-step procedures for deploy, rollback, backup, restore and common incidents
Architecture notesDiagram and short explanation of components, data flows and integrations
Test materialAutomated tests, test data and instructions for acceptance testing

Source code ownership is a contractual question as much as a technical one: agree who owns the code and when ownership transfers, and clarify the status of any pre-existing tools the supplier reuses across clients. Contract wording needs legal review by a qualified lawyer.

Environments and credentials

A handover is incomplete if you hold the code but not the keys. List every environment (development, staging, production) and for each one record where it is hosted, who can reach it, and how it connects to others.

  • Accounts belong to your company. Hosting, domain registrar, DNS, email-sending service, payment provider, analytics and error tracking should be registered to your organisation, with the supplier added as a user, not the other way round.
  • Use a password manager or secrets vault that your company controls. Credentials should never be handed over by email or chat.
  • Prefer named accounts with roles over a shared login, so access can be granted and revoked per person.
  • Rotate secrets at handover. After the pack is transferred, change keys and passwords the former team knew.
  • Record renewal dates for domains, certificates and licences, and who receives the reminders.

Keep production and test credentials separate, and make sure test environments do not contain unnecessary personal data.

Software handover documentation for runbooks and deployment

Deployment documentation answers: how does a change get from a developer's machine to production, and how do we undo it? Strong software handover documentation includes a runbook written so that someone who has never seen the system could follow it.

  1. Build and deploy. Exact commands or pipeline steps, prerequisites, and expected results at each step.
  2. Rollback. How to return to the previous version, including what to do about database changes.
  3. Backup and restore. Where backups go, how to restore, and who has done it.
  4. Routine tasks. Scheduled jobs, certificate renewal, log clean-up, adding a user.
  5. Incident notes. What to check first when the site is down, slow or sending errors, and who to call.

The best deployment documentation is partly executable: a script or pipeline definition in the repository that does the work, with the document explaining it. Scripts do not go stale as silently as prose.

Architecture notes and decisions

Code shows what the system does; it rarely shows why. Ask for a concise architecture overview: the main components, how they communicate, where data is stored, and which external services are used. A single diagram with a page of text beats fifty pages nobody reads.

Also ask for a short decision log. Each entry records a choice, the alternatives considered, and the reason: why this database, why that payment provider, why this approach to authentication. These notes save a new team from repeating discussions or undoing something deliberate. Include known limitations and open issues honestly. An honest list of technical debt is a sign of a mature supplier, and it helps you plan later work, such as the upgrade path described in modernizing business software in a Danish SME.

Acceptance and warranty period

Handover should be an acceptance event, not an email. Define in the contract:

  • The checklist of items the pack must contain, and who signs it off on your side.
  • Acceptance criteria for the software itself, with a test period during which you try it with real scenarios.
  • A warranty or support period after acceptance in which defects are fixed at no extra charge, with a clear definition of what counts as a defect rather than a change request.
  • A post-handover support window for questions from the new team, with response expectations.
  • Handling of residual items: payment may be linked to completion of the pack, so that documentation is not left to the end.

Our software vendor due diligence checklist lists further contract points to review with your adviser.

Testing the handover

Documentation that has never been used is untested. Before you accept it, run a rehearsal.

  1. Ask someone who did not build the system, such as an independent developer or your in-house IT person, to set up a fresh environment from the pack alone.
  2. Have them build the application, restore the database backup, and deploy a trivial change.
  3. Record every question they had to ask the original team; each one marks a gap in the documentation.
  4. Fix the gaps, repeat, and only then accept.

This single exercise tells you more than any amount of reading. Repeat it periodically, because documentation decays as the system changes.

Putting it together

Put the handover pack list into your contract at the start, hold the accounts yourself from day one, and ask for documentation during the project, not after it. If you already work with a supplier, request the pack contents now and run the rehearsal; discovering gaps while the relationship is good is much easier. To talk through a specific setup, see our page on software development for Danish companies.

Frequently asked questions

What should a handover pack include?

The complete source repository with build instructions, database schema and a restorable backup, configuration and dependency lists, infrastructure descriptions, runbooks for deploy, rollback and restore, architecture notes with key decisions, and test material. Define this list in the contract so it is a deliverable, and check it off at acceptance.

Who should hold the credentials?

Your company should own the accounts for hosting, domains, code repository, email and payment services, with the supplier invited as a user. Store credentials in a password manager or vault you control, use named accounts with roles, and rotate secrets when the project hands over.

How do I test that the documentation works?

Ask someone who did not build the system to create a fresh environment using only the handover pack: build the application, restore a database backup and deploy a small change. Note every question they had to ask. Each one is a gap to fix before you accept the handover.

Related articles

🚀 Start Now