"I wanted to switch vendors, but when I opened the project I found no docs, no account list, just a bundle of code I cannot read." A restaurant-chain owner described being held hostage this way: the system he paid NT$450,000 to build now costs another NT$100,000 just to understand how it runs. The root cause is not bad code; it is that handover documentation never existed from day one. This article covers what a responsible vendor should hand you so you can switch anytime and never be locked in.
Myths Debunked
- Myth 1: "Having the source code means you can take over." Reality: without deployment docs, environment config, and an account list, source code is a car with no key and no manual.
- Myth 2: "Docs are an extra service you pay for separately." Reality: basic handover docs are part of the deliverable, not an add-on. Professionals include them.
- Myth 3: "Just ask for docs when you need to switch." Reality: asking after the relationship breaks is when you are most likely to get nothing or a half-hearted version. Docs must be contracted for while things go well.
- Myth 4: "More docs is better." Reality: a precise doc that lets a new engineer boot the system within a day beats 100 unmaintained pages.
Core Framework: The 6 Categories of Handover Docs (None Optional)
- 1. System architecture diagram: how front end, back end, database, and third-party services connect.
- 2. Deployment and environment docs: how to boot the system from zero (env variables, dependencies, deploy steps).
- 3. Account and asset list: who owns hosting, domain, payments, API keys, email, SSL certificates.
- 4. Database schema notes: key tables and relations, meaning of critical fields.
- 5. Source code and version control: Git repo access, branch strategy, README.
- 6. Operations manual: common troubleshooting, backup/restore, monitoring and alerts.
The acceptance standard is one sentence: "Can an engineer who has never touched this project boot the system within a day using these docs?" If yes, it passes.
Three Typical Scenarios Compared
- 10-person startup (single system): at minimum, deployment docs + account list + README. Lean docs, but no missing key assets.
- 50-person mid-size (multi-system integration): needs the full 6 categories + architecture diagram, because undocumented cross-system dependencies are extremely costly to reconnect.
- 200-person enterprise (with internal IT): beyond the 6 categories, align with internal IT norms (security, audit trails, change logs); docs must be maintainable by the internal team.
Full Hidden-Cost List (the Price of No Docs)
- Onboarding cost: a new vendor typically charges NT$50,000-150,000 in "familiarization fees" just to understand the old system.
- Downtime risk cost: without an ops manual, one midnight outage can cost a whole day's revenue.
- Asset-reclaim cost: domain and payment accounts under the old vendor's name can take weeks to recover.
- Rework cost: with unclear docs, new vendors often just rewrite, paying development twice.
- Weak-negotiation cost: when locked in, you have no leverage and must accept the old vendor's renewal terms.
Vendor KPI Scorecard (Handover-Docs Dimension)
- Does the contract list handover docs as a deliverable? (0-2)
- Is a system architecture diagram provided? (0-2)
- Can deployment docs let a newcomer boot the system in a day? (0-3)
- Are accounts and assets registered under your name? (0-3)
- Is there a database schema note? (0-2)
- Is there an ops manual with backup/restore steps? (0-2)
- Is Git repo access handed to you? (0-2)
- Are docs updated with each version, not one-off? (0-2)
Out of 18, 14 or above means the safe, switch-anytime state.
ScriptWalker's Approach + When We Are Not a Fit
We write handover docs into every contract's deliverable list and offer three models: project-based (delivery includes all 6 doc categories), monthly maintenance (docs updated with each version), and a "doc health check" that audits gaps in your existing system's handover docs and fills them.
When we are not a fit (honestly):
- Clients who want only the cheapest one-off build with no docs; we do not do build-and-vanish projects.
- Clients who refuse to register accounts and assets under their own name; that only raises your risk.
- Those expecting one doc to last ten years without updates; systems change, docs need maintenance.
Kickoff Playbook (Bake Handover Into Day One)
- Week 1: contract lists handover docs as a deliverable; open a shared doc repo (Notion/Git Wiki).
- During development: docs update alongside code, not patched at the end.
- At launch: deliver the 6 doc categories + account list, and run one "switch test."
- Day 90: verify docs still match the system; set a quarterly update cadence.
Decision Checklist
- ☐ Does my contract list handover docs as a deliverable?
- ☐ Can I get a system architecture diagram?
- ☐ Can a new engineer boot the system in a day from the docs?
- ☐ Is the domain under my name?
- ☐ Are payment accounts under my name?
- ☐ Do I have Git repo access?
- ☐ Do I have a database schema note?
- ☐ Do I have an ops and backup/restore manual?
- ☐ Do docs update with each version?
- ☐ Have I run a "switch test"?
FAQ
Is it reasonable for a vendor to charge extra for docs?
Basic handover docs (deployment, accounts, architecture) should be part of the deliverable. Deep internal technical docs or training can be negotiated, but withholding even how-to-run is unreasonable.
What if I discover mid-project there are no docs?
While the relationship is still good, use a doc health check to fill gaps and write doc updates into the ongoing maintenance contract. Do not wait until you want to switch.
I am not technical; how do I accept docs?
Simplest test: have another engineer (or a new vendor) use only the docs to try booting the system. If it runs, they pass; if not, the docs fail.
Call to Action
Not sure if your handover docs are enough? We offer a free 30-minute "doc health check" consultation to inventory gaps and assess your lock-in risk.
- Email: [email protected]
- Phone: 0916-224-047
- LINE: @ufv9089p