IMHO, this is one of the three fundamental mistakes of literate programming:
1. Not everyone is an author or a teacher like Knuth is. Writing is actually hard.
2. A program is obviously not a linear thing. It is a network of interactions. The only way you can make it linear is to tell the tale of what happens in a given set of circumstances.
3. Docs and comments are prone to bitrot. You absolutely want to minimize then.
Everything that anyone has ever written a book about is also a non-linear network of interactions. Consider a textbook in any field. Physics is not a linear thing. Economics is not a linear thing. Even the thing a novel describes is not linear: characters are not linear, the world is not linear. You can linearize a program randomly, alphabetically, chronologically, or more usefully by order of module dependency.
Yes. There is never one view of a program, but multiple architectural views.
Literate programming in the sense of documenting a program like a monograph is too one-dimensional.
I would like to see an emphasis on test inputs/outputs instead. Given all the Test vectors the actual code becomes irrelevant. It seems that we focus on the code because it used to be the bottleneck, plus it’s the densest piece of information in the system…and takes less paper to print.
In a world where modules must be constantly integrated, I’d rather read the test traces than the code itself.
Good programmers can simulate the code in their heads and internally generate the traces…but presumably the point of literate programming should be to remove that burden from the reader.
IMHO, this is one of the three fundamental mistakes of literate programming:
1. Not everyone is an author or a teacher like Knuth is. Writing is actually hard.
2. A program is obviously not a linear thing. It is a network of interactions. The only way you can make it linear is to tell the tale of what happens in a given set of circumstances.
3. Docs and comments are prone to bitrot. You absolutely want to minimize then.