Principlev1PR-313
When documentation describes system decisions, prioritize…
When documentation describes system decisions, prioritize explaining why a choice was made over describing what was chosen, because 'why' context remains useful after 'what' implementation details become obsolete.
Why This Is a Principle
This derives from Abstraction Necessarily Discards Information (abstraction necessarily discards information, retaining only selected features deemed relevant) and Knowledge that exists only in tacit form degrades without… (knowledge that exists only in tacit form degrades without detection). The lesson presents ADRs as a practice that captures 'why' context because implementation changes but constraints and trade-offs persist. This is prescriptive documentation guidance derived from axioms about abstraction and tacit knowledge.