Chapter 13: Knowledge Transfer and Graduation
As mentioned, as an FDE you are aiming to move into projects, provide an unprecedented level of value, bring a project to completion and then determine when to transfer the project back to stakeholders or to a less involved support phase. It’s important to keep this in mind from the genesis of the project.
This mainly impacts the technical frameworks, coding practices, and maintainability of the system that you are creating. When making architectural decisions, they need to be defensible from a handoff perspective. Unless the scope mandates it, client projects are not the places to experiment with new and obscure technology. If you want to build a project in a new javascript framework that came out last week, that is to be done on your own time. Our technical dependencies should be in popular frameworks, libraries, design principles etc. Essentially, a support developer, FTE, or external developer should be reasonably able to maintain or contribute to the project. This is important to keep in mind when curating those technical dependencies.
Additionally, the codebase should be clean and well documented. Most of this should be handled in the last phase of the development process, but understand that organizing and documenting the codebase is more than just for codebase aesthetics - its core purpose is to facilitate project transfers to FTEs or client teams. Next, let’s talk about documentation of the project.
There are three core documentation assets that are involved in all projects. Most of the time, no one reads documentation for entertainment purposes. People read documentation when there is a specific problem that needs to be investigated and solved and these assets are curated around this assumption.
The first asset is the Operational Runbook. This is the document that the person maintaining the software will actually use. It covers how to deploy, how to roll back, how to monitor, how to handle common issues, where the environment variables live, what the third-party dependencies are and how to update them, and what to do when something breaks at 2 AM. It’s structured as a series of “if this, then that” scenarios. Short. Direct. No preamble. If you can’t find the answer to an operational question within sixty seconds of opening this document, we’ve failed.
The second asset is the System Overview. This is the document for someone who needs to understand the system at a conceptual level before making changes. It covers the architecture, the data model, the key design decisions and why they were made, the integrations and how they work, and the areas of the system that are most sensitive to change. This document is not a tutorial — it assumes the reader is a competent developer. Its job is to transfer the institutional knowledge that lives in our heads to a document that outlives the engagement. The “why” is as important as the “what” here. Knowing that we chose a specific database indexing strategy is useless without knowing why — and under what conditions that decision should be revisited.
The third tier is the Spec Tree itself. As discussed in Chapter 7, the Spec Tree is the most comprehensive representation of the project. For handoff purposes, it serves as the detailed blueprint that any development team could use to understand not just what was built, but the specification it was built against. This allows the client’s team — or a future vendor — to evaluate the software against its original intent and make informed decisions about modifications.
The Three-Tier Handoff Documentation Stack
┌───────────────────────────────────────────────────────────────────────┐ │ │ │ TIER 1: OPERATIONAL RUNBOOK │ │ │ │ For: The person maintaining the software │ │ Format: "If this, then that" — find answers in 60 seconds │ │ │ │ Deploy / rollback procedures │ │ Monitoring & alerting │ │ Common issues & fixes │ │ Environment variables & secrets │ │ Third-party dependency management │ │ 2 AM incident response protocols │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ TIER 2: SYSTEM OVERVIEW │ │ │ │ For: Developers who need to understand before changing │ │ Focus: The WHY, not just the WHAT │ │ │ │ Architecture & data model │ │ Key design decisions and rationale │ │ Integrations and how they work │ │ Sensitive areas (handle with care) │ │ When to revisit specific decisions │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ TIER 3: SPEC TREE │ │ │ │ For: Complete project blueprint │ │ Use: Evaluate software against original specification │ │ │ │ Full hierarchical specification │ │ Feature groups, implementation plans, atomic tasks │ │ Acceptance criteria for every component │ │ Living document — reflects the project as built │ │ │ └───────────────────────────────────────────────────────────────────────┘
Documentation can facilitate handoff, but oftentimes training is needed for the teams assuming ownership to ensure a proper transition. Training is nuanced in different scenarios. If we are handing ownership to a Benmore FTE, this process is a lot smoother as our development practices are already aligned, and consumption of project context is optimized. Things become a bit more complicated when training and working with client’s internal teams.
What we typically do with client’s internal teams in relation to hand off is predicate everything around development based training. Specifically, we have found that the most effective way for developers to understand an existing system is to contribute to it. Regardless of the team receiving the project’s development practices, we set up an AI knowledge agent. This is an instance of Claude Code that lives within a cloned and sandboxed version of the project, and has been prompted to answer questions in relation to the codebase. It knows about the project Spec Tree, the codebase, and has knowledge of all other delivery assets.
Knowledge Transfer Checklist
Documentation:
AI Knowledge Agent:
Training Projects Prepared:
Handoff Execution:
We then curated a list of projects for developers to complete that cover common development scenarios in relation to the project. Identifying and fixing a bug, rolling back deployment to a previous version, committing a feature etc. This allows room for developers to learn through experience rather than information bombing them. Our goal here is to exit from the project and transfer ownership, if we are able to do that effectively then our role as an FDE is fulfilled.