Definition
The ratio of documented decision rationale (the "why" behind code decisions) in post-modernization documentation to the identifiable decision points in the modernized code, measuring whether modernization captures institutional knowledge or merely converts syntax.
The Measurement Gap
There is no metric that tells you whether institutional knowledge embedded in legacy code was captured during modernization or lost, which means documentation volume can increase while documentation value decreases.
Formula
Plain language: Count the decision points in the modernized code (conditional branches, algorithm choices, configuration values, exception handlers). Then count how many of those decision points have documentation that explains the rationale, not "this function calculates the discount" but "this discount calculation uses a 3% threshold because contract #4472 with Acme Corp specifies volume discounts above 1,000 units." The KED is the ratio.
Notation:
KED = (DP_documented_with_rationale / DP_total) × 100
Variables:
- DP_documented_with_rationale = decision points in modernized code that have accompanying documentation explaining the business rationale, regulatory basis, or historical context for the decision (count, MANUAL: requires human assessment of documentation quality)
- DP_total = total identifiable decision points in the modernized code (count, DERIVED from static analysis: conditional branches, algorithm selections, configuration values, exception handlers)
Documentation quality criteria (must meet at least one to count as "documented with rationale"):
- Explains the business rule or regulatory requirement that drives the logic
- References a specific contract, regulation, customer requirement, or historical decision
- Explains why a particular approach was chosen over alternatives
- Documents a known constraint or dependency that influenced the implementation
Documentation that merely restates the code in English ("this function returns the sum of x and y") does NOT count.
Proposed formula, pending validation pilots.
At a Glance
Decision Supported
When the AI modernizes legacy code and generates new documentation, does the documentation explain why the code works the way it does, or does it just describe what the code does? Are we losing decades of institutional knowledge during modernization?