Code is a mixture of what and how (and with IaC, sometimes who and where). I agree that "why" is the role of documentation. I've been experimenting with tying

Code is a mixture of what and how (and with IaC, sometimes who and where). I agree that "why" is the role of documentation. I've been experimenting with tying the two together with (machine checked, automatically surfaced) cross-references, so we can better know what bits of documentation a test supports, &c. I haven't yet gotten rigorous about it.