Appendix C — Model Reference

C.5 Documentation and Provenance

Provenance models record what happened. Documentation models represent the human-facing claims that should remain synchronized with those facts. In review, they expose whether required records exist and whether derived documentation still reflects its source.

Engineering question. What happened, and which human-facing account of it must remain true?

Representation.

Action
    id
    artifact
    operation
    actor
    mechanism
    timestamp
    result
DerivedDocumentation
    source_fact
    rendered_claim

Where documentation can be derived from structured facts, generate it from those facts rather than maintaining an independent copy.

Figure C.5-1 puts the fact before the prose.

Facts before prose — the strongest documentation is generated from facts the system already knows An engineering action leaves a provenance fact recording what, who, and how, along a solid arrow. From that fact two solid branches descend. The left branch, validation and audit, is mechanically checkable: it reaches a heavy bordered node crossed by a gate glyph, a completion gate with real authority. The right branch, generated documentation, is solid and re-derivable; it produces a faithful human explanation. Separately, prose maintained independently carries a dashed drift-risk arrow to a dashed hazard box — free prose can diverge from the implementation because no machinery re-derives it. Legend as in Figure C-1; weight, dash, and glyph carry the meaning without colour. Question: what happened, and which account of it must stay true? validation / audit generated re-derivable ENGINEERING ACTION PROVENANCE FACT what · who · how VALIDATION / AUDIT CHECKED · completion gate GENERATED DOCUMENTATION human explanation prose maintained independently no mechanical correspondence Generate from facts the system already knows — do not keep a second hand-maintained copy. Legend: see Figure C-1. Solid + re-derivable stays faithful; a dashed prose edge may drift.
Figure C.5-1. Facts before prose. A structured provenance record supports mechanical validation and re-derivable documentation; independently maintained prose lacks that correspondence.

Property. Representative properties:

Authority and correspondence. Structured provenance can be validated mechanically, and generated documentation can be re-derived from its source facts. Free prose generally cannot be checked for semantic equivalence by the same machinery and therefore remains subject to human review.

© James C. Davis, 2026–present