The Documentation Was Written Once. It's Been Trusted Ever Since. It's Wrong.

The architecture document was written during the initial design sprint, updated once when the team refactored the auth layer, and has been the go-to reference for every new hire since. It describes the system as it was designed to work. It does not describe the system as it currently works — the service that was split into two, the database schema that changed for performance reasons, the integration that was replaced but still has legacy traffic routed through it. The document is trusted because it's the official record. It's inaccurate because systems change and documentation doesn't.

Documentation-as-institutional-knowledge fails not because engineers don't write it. It fails because the system changes constantly and documentation updates are always second priority to shipping. The result is a document that was accurate when it was written, is increasingly wrong over time, and is treated as authoritative by every engineer who hasn't already learned to distrust it.

How documentation becomes wrong

Documentation becomes wrong gradually, through a series of reasonable decisions. A service gets refactored — the engineer updates the code, the tests, and the PR description, but not the architecture doc. A schema changes — the migration runs, the ORM models update, but the data model document still shows the old structure. A configuration setting gets added to handle a production edge case — there's a commit message explaining it, but the README still describes the original configuration.

None of these omissions are negligent. Updating documentation during a code change is genuinely lower priority than making the code change correctly. But the accumulation of these omissions over months and years produces a document that has drifted significantly from the actual system — and the drift is invisible to anyone reading only the document.

The documentation lifecycle:

  Year 0: Written during or after initial implementation
  -> Accurate at time of writing
  -> Covers the architecture as designed
  -> Missing edge cases discovered post-launch

  Year 1: First major system changes
  -> 2 services refactored, docs not updated
  -> New data model, docs reference old schema
  -> "TODO: update docs" added in Slack, not done

  Year 2: Team changes
  -> Original authors mostly gone
  -> No one confident enough to rewrite the docs
  -> Docs treated as "probably still mostly right"

  Year 3+: Documentation as archaeology
  -> Teams cross-reference docs with code to find contradictions
  -> New engineers assume docs are wrong until proven otherwise
  -> "Don't trust the docs, read the code" is institutional wisdom

The trust problem

Stale documentation is worse than no documentation, in a specific way. No documentation tells you nothing; stale documentation tells you something wrong with apparent authority. A new engineer who encounters outdated docs doesn't know they're outdated — they build a mental model of the system based on inaccurate information, make decisions from that model, and discover the error when their assumptions don't match production behavior.

Teams that have experienced this enough times develop informal norms: "always check the code," "the docs are probably wrong," "ask someone who's actually worked in that service." These norms are a rational adaptation to stale documentation. They also mean that the institutional knowledge the documentation was supposed to preserve routes through people instead — back to the tribal knowledge problem that documentation was supposed to solve.

What the codebase captures that documentation doesn't

The codebase is always current because it has to be — the code running in production is the code in the repository. Every schema change required a migration. Every refactored service left traces in the imports and call graph. Every workaround is in the file where it lives. The codebase doesn't decay the same way documentation does because the system can't run without it being accurate.

What documentation systematically fails to capture:
  -> The edge cases discovered after the initial release
  -> The workarounds added for bugs that were never fixed
  -> The services that were deprecated but still called in one place
  -> The configuration that "must stay this way" with no written reason
  -> The migration that was half-finished and left in production
  -> The third-party API behavior that differs from its own documentation
  -> The performance characteristic that only appears under specific load

  All of this is in the codebase.
  None of it is in the documentation.
  The codebase is always current. The documentation rarely is.

Kognita makes the codebase queryable in the same way documentation is supposed to be. Instead of reading an architecture document that may be years out of date, engineers and non-engineers can ask questions about how the system actually works — and get answers from the live code, not from a snapshot of how the system was designed to work in a prior year.

Final take

Documentation written once becomes wrong gradually and trusted permanently — a dangerous combination. The codebase is always current because it has to be. Teams that treat the codebase as the source of truth instead of the documentation artifact have a more reliable foundation for system knowledge — even if it's harder to read without the right tools.

The docs were accurate when they were written. The system changed. The docs didn't. The codebase knows the truth. The docs know the history.