Documentation as schema preservation

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:

1. Nygard, M. (2011). "Documenting Architecture Decisions." Cognitect Blog.