Separate what is known from what still needs verification
When a developer or team leaves a legacy system, a significant portion of what makes that system work exists only in their heads. Business rules that were never written into the specification, workarounds applied during production incidents, deployment steps that only one person has ever run, and the reasons certain architectural decisions were taken — none of these reliably appear in code comments or project documentation.
Knowledge transfer is the structured process of extracting that tacit understanding before it walks out the door. It is not a single handover meeting or a forwarded email thread. It is a time-bound exercise with specific goals: to reduce the risk of the incoming team making incorrect assumptions, to surface hidden dependencies, and to create a written record that the business can refer to long after the outgoing developers have gone.
The exercise sits between two other activities that are covered separately. Onboarding the new team to the codebase is about how the incoming developers read, build and test the existing software. Deciding whether to rebuild or modernise is a strategic choice about the system's future. Knowledge transfer, by contrast, is narrowly about what the outgoing people know that is not captured anywhere else, and how to get it into a durable form.
What typically lives only in developers' heads
- Which parts of the codebase are safe to change and which will break apparently unrelated features.
- Undocumented environment variables, feature flags and configuration values that differ between staging and production.
- The real business rules — the ones that were explained verbally, adjusted on a phone call, and never updated in the requirements document.
- Known bugs that the business has learned to work around rather than fix.
- The sequence and timing of manual steps that happen outside the application but are essential to its operation.
- Third-party service accounts, API keys and the names of people at those providers who were contacted during original setup.
- Historical context for why a seemingly strange technical decision was made at the time.
Not all of this knowledge is equally valuable. Part of the transfer process is distinguishing what the incoming team genuinely needs from what is merely interesting context.
Structuring the transfer sessions
Unstructured conversations rarely produce useful records. A more effective approach is to prepare a topic list in advance, share it with the outgoing developers so they can gather their thoughts, and run focused sessions of no more than ninety minutes each. Longer sessions produce diminishing returns as fatigue sets in.
Each session should cover one category of knowledge: deployment and infrastructure, business rules and process exceptions, known issues and workarounds, third-party integrations, and access credentials. Having a note-taker who is not the person asking questions allows the interviewer to focus on probing rather than typing.
Questions that surface useful answers
Vague questions produce vague answers. Asking "tell us about the system" will generate a high-level overview that the incoming team could have worked out for themselves. More productive questions target the gaps:
- "If you had to deploy this to a new server tomorrow, what steps would you follow that are not in any documentation?"
- "Which configuration values would break the application if they were set incorrectly, and what are the correct values?"
- "What business rules have changed since the original specification was written?"
- "Which features do users complain about most, and what is the current workaround?"
- "Are there any cron jobs, background tasks or external scripts that must run for this system to work?"
- "Which third-party services would stop working if nobody renewed a contract or updated a payment method?"
- "If you could change one thing about this codebase, what would it be and why?"
The last question often reveals the most practically useful information, because it points directly at the area of greatest technical debt.
Recording and verifying what you are told
Verbal answers are not evidence. Everything stated in a transfer session should be captured in writing and, where possible, verified against the system itself. If a developer says a particular environment variable controls a specific behaviour, check the code. If they say a third-party API is called once per day, check the logs.
This verification is not about distrusting the outgoing team. It is about recognising that memory is imperfect and that developers often describe how a system should work rather than how it actually works after years of patches and shortcuts.
When the outgoing developer has already left
In practice, knowledge transfer often begins after the original developers are no longer available. The business has a legacy system, the agency relationship has ended, and nobody on the current team built the software. In this situation, the transfer has to come from the system itself: reading the code, examining logs, testing behaviours, reviewing commit history and speaking with internal users who know what the system is supposed to do. This is slower and less reliable, which is precisely why transfer should be planned while the original team is still engaged.
Access handover as part of transfer
Credential transfer is a distinct but related activity. The outgoing team should provide a complete list of every account, key and token required to operate the system: hosting control panels, domain registrars, database access, third-party API accounts, email service providers, error-tracking tools and any other services the application depends on. Each item should include the account name, the current access level, and instructions for how the business can reset the credentials if needed. Simply receiving a password is insufficient; the business must be able to regain access independently if those credentials are later revoked.
Treating transfer as a single meeting
The most frequent mistake is scheduling one two-hour handover and considering the job done. Knowledge transfer for a non-trivial legacy system typically requires multiple sessions spread over days or weeks, combined with follow-up questions as the incoming team begins working with the codebase and discovers new gaps. The contract or departure timeline should explicitly allocate time for this.
Assuming the documentation is complete
If the existing documentation were sufficient, there would be no need for a knowledge transfer exercise. Starting from the assumption that the documents are incomplete and treating the transfer sessions as a way to find out what is missing produces better results than reading the documentation first and only asking about gaps.
Not involving the right people
Developers can explain technical architecture, but they often cannot accurately describe how business users actually interact with the system day to day. Including an operations manager or an experienced end-user in at least one transfer session helps surface discrepancies between how the system was designed and how it is used.
Accepting answers without testing them
If an outgoing developer states that a particular process works in a certain way, the incoming team should reproduce that process before accepting the claim. Legacy systems accumulate undocumented states and edge cases that even the original developers may not recall accurately. Verification turns anecdote into reliable information.
Key checks before signing off transfer as complete
- The incoming team can build and deploy the application to a staging environment without assistance from the outgoing team.
- All known third-party service accounts have been identified, access has been tested, and the business holds credentials or a documented reset process for each.
- Documented business rules have been reviewed by someone who understands the operational process, not only by developers.
- Known issues and workarounds have been recorded with enough detail for a new team member to understand the problem and the current mitigation.
- Commit history and deployment logs have been reviewed for any automated processes or scheduled tasks that were not mentioned in transfer sessions.
- The outgoing team has confirmed, in writing, that they have disclosed all known critical information — understanding that this confirmation covers what they remember, not what they may have forgotten.
Recognising the inherent limitation
Knowledge transfer cannot capture everything. There will be questions that nobody thinks to ask until a specific situation arises months later. The realistic goal is not perfect knowledge but sufficient knowledge: enough context for the incoming team to investigate problems confidently, enough access to operate the system independently, and enough written record to avoid repeating conversations that have already happened. Accepting this limitation upfront leads to better planning than expecting a complete handover that no transfer exercise can truly deliver.