1. Specs&design docs and code should be in separate files, because I believe the separation of concerns should be applied there. That's indeed the opposite of literate programming.
2. There should be two-way links between documentation and code: in the code, one should have links to the spec; and from the spec, one should have links to the code.
3. If the specs or the code changes, those links should be displayed in a different way to warn the reader that things are potentially not in sync. How to do that: check if the links point to the latest version. The maintainers have to update the links to remove the warnings.
Specification and design/implementation are not separate concerns. They are dual.
A sufficiently detailed specification is an implementation. Prolog does this (and Eve has a very similar feel).
As engineers, we traditionally work declaratively at the top of the "V" and imperatively at the bottom of the "V" -- but the reasons for this are largely historical/cultural.
We could (in theory) carry out the analysis/refinement process using entirely declarative notation.
The problem domain has primacy. Analysis separates problem-domain concerns and the duality takes care of the translation between problem and solution domains.
(OK -- so this is basically just a reiteration of the thesis of good old-fashioned AI -- that with a sufficiently powerful theorem prover and a sufficiently large and detailed knowledge base -- solutions will just pop out of a largely mechanical analysis process -- and I'm pretty sure this isn't at all trendy right now ... so I should relegate this to the "thinking out loud" bucket ...)
1. Specs&design docs and code should be in separate files, because I believe the separation of concerns should be applied there. That's indeed the opposite of literate programming.
2. There should be two-way links between documentation and code: in the code, one should have links to the spec; and from the spec, one should have links to the code.
3. If the specs or the code changes, those links should be displayed in a different way to warn the reader that things are potentially not in sync. How to do that: check if the links point to the latest version. The maintainers have to update the links to remove the warnings.