Documentation as schema preservation
~6 min read
Core Primitive
Documentation is not just a record of what exists.
It is a preservation mechanism for organizational schemas — the shared mental models that explain why things are the way they are, not just what they are. Documentation that captures schemas (the reasoning, the context, the tradeoffs) preserves the organization's cognitive capacity. Documentation that captures only facts (the current state, the procedure, the configuration) preserves information but not understanding.
The difference between preserving information and preserving understanding
Most organizational documentation answers the question "What?" What is the system architecture? What are the deployment steps? What are the configuration options? This factual documentation is necessary. But it is insufficient for preserving organizational intelligence, because it captures the current state without capturing the reasoning that produced it.
The reasoning — why the architecture uses microservices rather than a monolith, why the deployment requires a manual approval step, why the configuration has a specific default value — is the schema. It is the mental model that explains not just what exists but why it exists in this form rather than some other form. When the schema is preserved, future decision-makers can evaluate whether the original reasoning still applies and make informed decisions about modification. When only the facts are preserved, future decision-makers must either reverse-engineer the reasoning (slow and error-prone) or make decisions without it (fast and dangerous).
Michael Nygard, who coined the term "Architecture Decision Records" (ADRs), articulated this distinction clearly: "Documentation of the architecture should capture the decisions that led to the current state, not just the current state itself. The decisions are the interesting part — they encode the context, the constraints, and the tradeoffs that the current architecture embodies." Nygard's ADR format — context, decision, status, consequences — is explicitly a schema preservation format: it captures the mental model that produced the decision, not just the decision itself (Nygard, 2011).
What schema documentation looks like
Schema documentation takes several forms, each suited to preserving different aspects of organizational thinking.
Architecture Decision Records (ADRs). A short document for each significant design decision, recording: the context (what was the situation?), the decision (what was chosen?), the alternatives (what else was considered?), and the consequences (what does this decision enable and constrain?). ADRs preserve the decision-making schema — the reasoning process that produced the current architecture. When a future engineer asks "Why is it built this way?" the ADR provides the answer without requiring the original decision-maker to be present.
Incident retrospectives. A structured post-incident document recording: what happened, why it happened (root cause analysis), how it was resolved, and what will change to prevent recurrence. Incident retrospectives preserve the diagnostic schema — the reasoning process through which the team identified and resolved the problem. Future teams facing similar incidents can access the diagnostic reasoning rather than starting from scratch.
Design proposals. Documents written before a decision is made, describing the problem, proposing a solution, presenting alternatives, and analyzing tradeoffs. Even when the final implementation diverges from the proposal, the document preserves the problem schema — the team's understanding of what problem they were solving and what constraints they faced. This context is often more valuable than the solution itself, because the problem persists even when the solution is replaced.
Process rationale documents. For each significant process (deployment, incident response, on-call, code review), a brief document explaining why the process exists, what risks it mitigates, and what assumptions it embeds. Process rationale documentation prevents the common failure where a process persists long after its original justification has expired — because the justification was never documented and is therefore unavailable for re-evaluation.
The documentation lifecycle
Documentation that is written once and never updated degrades from an asset into a liability. Effective schema documentation follows a lifecycle.
Creation. Documentation is created at the moment the schema is formed — when a decision is made, an incident is resolved, or a process is designed. This is the moment of maximum contextual richness: the reasoning is fresh, the alternatives are remembered, and the tradeoffs are salient. Documentation created weeks or months after the fact captures a faded version of the schema, with details lost and reasoning reconstructed rather than recorded.
Maintenance. Documentation is reviewed periodically to ensure accuracy and relevance. The review can be triggered by time (quarterly review of all ADRs), by event (review relevant documentation after any significant system change), or by usage (update documentation whenever someone reads it and finds it outdated). The review practice prevents documentation decay — the gradual divergence between the documented schema and the actual system.
Retirement. Documentation that is no longer relevant — because the system was replaced, the process was retired, or the decision was superseded — is explicitly marked as historical rather than current. Historical documentation is not deleted (it may provide valuable context for understanding why the current system exists) but is clearly labeled so that readers do not mistake outdated schemas for current guidance.
Discovery. Documentation that cannot be found might as well not exist. Organization's documentation systems must support discovery: search, navigation, cross-referencing, and integration with the tools that people use daily. A perfectly written ADR buried in a wiki subfolder that no one visits preserves knowledge in theory but not in practice.
The schema documentation practice
Building a schema documentation culture requires more than mandates — it requires embedding documentation into existing workflows so that schema capture happens as a natural byproduct of work rather than as an additional obligation.
Decision documentation as decision process. When the organization's decision-making process includes "document the decision and its rationale" as a step — not an optional follow-up but an integral part of the decision process — schema documentation happens automatically. Some organizations require an ADR before a technical decision can be considered final, making documentation a precondition rather than an afterthought.
Incident learning as incident response. When the incident response process includes a retrospective as a required step — with specific prompts for root cause, diagnostic reasoning, and systemic improvements — schema documentation happens as part of incident resolution rather than as a separate activity that competes for time with the next fire.
Onboarding as documentation audit. When new members are expected to read existing documentation as part of onboarding and report gaps, inaccuracies, and confusion, the onboarding process serves double duty: it educates the new member and audits the documentation. New members' confusion reveals documentation failures that experienced members cannot see because their own tacit knowledge fills the gaps.
The Third Brain
Your AI system can transform schema documentation from a laborious writing exercise into a natural capture process. During design discussions, decision meetings, or incident resolutions, record the conversation and share it with the AI. Ask: "Write an Architecture Decision Record based on this conversation. Extract the context, the decision, the alternatives discussed, and the consequences identified." The AI produces a first draft that captures the schema while the context is fresh, which a human reviewer can then refine and publish.
The AI can also help maintain existing documentation. Share a set of documents with current system information and ask: "Compare these ADRs against the current system state. Which decisions have been superseded by subsequent changes? Which assumptions in the ADRs are no longer valid? Which consequences have materialized?" The AI's analysis identifies documentation that needs updating, preventing the decay that makes documentation unreliable over time.
For schema documentation quality assessment, use the AI to evaluate existing documents: "Read this documentation and tell me: Does it capture why the system is designed this way, or only what the design is? What questions would a new engineer have after reading this that the documentation does not answer? What schema knowledge is implied but not stated?" The AI's assessment reveals the gap between facts-only documentation and schema documentation, providing specific guidance on what to add.
From preservation to learning
Documentation preserves existing schemas — it captures the organization's current understanding so that it persists beyond individual memory and tenure. But organizations must not only preserve their schemas — they must also update them in response to new experience, new information, and new environments. This capacity to update schemas in response to feedback is organizational learning.
The next lesson, Organizational learning, examines organizational learning — the mechanisms through which organizations update their shared mental models, and why many organizations fail to learn even when the feedback is clear and the consequences of not learning are severe.
Sources:
- Nygard, M. (2011). "Documenting Architecture Decisions." Cognitect Blog.
Put it into practice
Exercise
Choose one important system, process, or decision that your team is responsible for. Check the existing documentation. Does it capture only what (current state, procedures, configurations) or does it also capture why (design rationale, alternatives considered, tradeoffs accepted)? If the documentation is facts-only, write a one-page schema supplement: 'This system was designed to solve [problem]. The key design decisions were [1, 2, 3]. For each decision, the alternatives considered were [X, Y] and the reason this option was chosen was [reasoning]. The most important tradeoff this design accepts is [tradeoff].' This one page preserves more organizational intelligence than ten pages of factual documentation.
More on putting it into practice
See it in action
Two engineering teams at the same company maintained internal wikis of similar size — approximately 500 pages each. But the quality of knowledge preserved was dramatically different. Team A's wiki consisted primarily of factual documentation: API references, configuration settings, deployment steps. Each page described what something was and how to use it. Team B's wiki included factual documentation but also captured schemas: Architecture Decision Records explaining why the system was designed a certain way, incident retrospectives explaining how failures were diagnosed and what was learned, and design proposals documenting the alternatives that were considered and rejected. When both teams experienced 40% turnover in the same year, the impact was markedly different. Team A's new members could operate the system — the factual documentation told them what to do — but could not make design decisions, because they did not understand why the system was built the way it was. Every architectural question required finding one of the remaining original members and asking for context. Team B's new members could both operate and evolve the system — the schema documentation gave them the reasoning behind the current design, which enabled them to make decisions consistent with the established architectural direction without asking for permission or context. Team B's documentation had preserved not just information but organizational intelligence.
Watch for the failure mode
Two opposing failures. The first is documentation as archaeology — creating documentation that is so detailed and comprehensive that it becomes impenetrable. A fifty-page document that captures every nuance of a system's history but cannot be navigated or searched effectively preserves knowledge in theory but not in practice. Good schema documentation is concise: it captures the key decisions, the key reasoning, and the key tradeoffs, not every conversation and every email. The second failure is documentation as obligation — creating documentation because the process requires it rather than because it serves a knowledge preservation purpose. Documentation written to satisfy a checklist rather than to inform a future reader captures form without substance. The test of documentation quality is not whether it exists but whether a new team member would find it useful.
Make it stick
Return to Institutional knowledge loss, which examined institutional knowledge loss. Documentation is the primary defense against knowledge loss — it converts person-node knowledge into document-node knowledge that persists beyond individual tenure. But documentation quality matters: facts-only documentation preserves information without understanding, while schema documentation preserves the reasoning that enables future decision-making. The connection to (making team thinking visible through externalization) is direct: documentation is externalization at the organizational level, and the same principles apply — what is externalized can be examined, shared, and preserved; what remains internal is vulnerable to loss. Look forward to Organizational learning, which examines organizational learning — the organization's capacity to update its schemas in response to experience.
Practice
Document System Schema in Notion with Decision Rationale
You will create a schema-preserving documentation page in Notion that captures not just what a system does, but why it was designed that way, including alternatives considered and tradeoffs accepted.
- 1Open Notion and create a new page titled 'Schema Documentation: [Your System Name]'. Add a database property called 'Documentation Type' and set it to 'Schema Preservation' to distinguish this from factual documentation.
- 2Create a section called 'Problem & Purpose' at the top of the Notion page. Write 2-3 sentences describing the specific problem this system was designed to solve and its intended purpose, focusing on the why rather than the what.
- 3Add a section called 'Key Design Decisions' and create a Notion toggle list with 3-5 major design choices. For each toggle, write the decision as the heading, then inside the toggle document: the alternatives that were considered, the specific reasoning for choosing this option, and any assumptions that influenced the choice.
- 4Create a section called 'Accepted Tradeoffs' and use a Notion table with columns for 'Tradeoff', 'Why We Accept It', and 'Monitoring Strategy'. Document 2-3 significant tradeoffs this design accepts, explaining what was sacrificed and why it was worth it.
- 5Add a final section called 'Schema Preservation Date' with today's date and the names of key decision-makers. Link this Notion page to your system's factual documentation using Notion's mention feature, creating a bridge between what exists and why it exists this way.