V. Embedded Knowledge

The Requirement

Documentation, runbooks, and architectural decisions must be versioned with implementation.

The Problem

Documentation is the great casualty of the time crunch. “You can always write that wiki page later,” says the devil on your shoulder. But you never do.

When documentation does exist, it is external to the code. It could be on a documentation site, a shared drive, or a README that was last updated two years ago. When you rollback from the latest version to 1.9.5, the documentation still describes the latest version. The Asset and its explanation have diverged.

The Practice

A hermetic asset contains its own knowledge:

• READMEs at every significant directory explaining purpose and usage
• Architectural Decision Records (ADRs) justifying decisions
• Runbooks describing operational procedures for incidents
• API documentation generated from code or maintained alongside it

Version 1.9.5 always carries the correct version of the documentation. There is no more knowledge drift or out of date docs.

The Litmus Test

If your entire engineering team was replaced tomorrow, could a new team understand why the architecture is built this way? Could they operate it in production? If institutional knowledge lives only in people’s heads, your asset is incomplete.

What This Enables

The Asset justifies its own existence - it explains what it does, how it works, and why it exists. New engineers can onboard from the repository alone. If we ever need to deploy an old version, we have up to date documentation as part of The Asset.

Without embedded knowledge, The Asset has an expiration date equal to the tenure of its creators. When they leave, understanding leaves with them. The Asset becomes legacy: functional but incomprehensible, maintained through fear rather than confidence.

A complete asset is immortal. Its knowledge persists regardless of team turnover.