What goes wrong when you ignore that documentation as schema preservation?

The most common reason fails: 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.

The fix: 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.

The underlying principle is straightforward: 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.