Important product knowledge can disappear from view when it lives only in one person’s memory. In this lesson, Carlos Sanabria explains why documentation matters for onboarding, delegation and continuity.
The practical test is whether a new engineer can understand the system and begin useful work without relying on an extended personal tour from its original author.
What you'll learn.
- Make architecture and important decisions understandable to a new engineer.
- Identify knowledge that depends on one person.
- Keep useful context available for both developers and AI-assisted work.
Test the onboarding experience.
Ask how quickly a new developer can become productive. Can they locate the relevant parts of the code, understand how the system runs and identify the information needed for an initial change?
The goal is not to eliminate conversation. It is to prevent every basic question from depending on a particular person being available. Repeated onboarding questions are useful signals about what the documentation is missing.
Record architecture and decisions.
Document the structure of the system and the reasons behind important choices. A diagram or file list can show what exists, but an explanation of the decision helps another engineer judge how to change it.
Keep that information close enough to the work that people can find and maintain it. When the system changes, revisit the notes that would otherwise send the next person in the wrong direction.
Identify single-person dependencies.
Carlos asks what would happen if the lead developer left. Which parts of the product would become difficult to understand, operate or modify? That question exposes continuity risks before a handoff becomes urgent.
The recording uses a library analogy to describe the loss of shared knowledge. The actionable point is to make critical context durable and accessible, rather than relying on an informal explanation that disappears when a person is unavailable.
Provide context for AI-assisted work.
AI agents also need relevant information about the product and its constraints. Without it, each task can begin from an incomplete picture of how the system is supposed to behave.
Useful context includes architecture, important business rules and the reasoning behind choices a contributor should preserve. Treat documentation as working material for future changes: clear enough to guide a task, specific enough to prevent avoidable misunderstandings and maintained as the product evolves.
Documentation makes a product easier to hand over and safer to change. Start with the knowledge the next contributor needs, then keep it connected to the decisions and system it explains.
