If you want to read a thoughtful and valid criticism of Knuth’s ideas, I recommend https://www.cs.tufts.edu/~nr/pubs/lpsimp-abstract.html by Norman Ramsey. The observation that rang most true for me was: literate programming should be written in the style of a car manual, not a novel.
Noweb was an amazing little tool. Very sweet clean architecture with a simple straightforward textual intermediate representation, accessible to simple pipelined processing, and a lovely community of add-ons.
And then? It was reimplemented in 'icon', incompatible Proteine, too, and the community feel apart.
That's a real pity because noweb got almost everything right.
However.
Imnsho the real challenge for literate programming is IDE support. Not only do you embed languages into each other. In addition you chip chop your code into fragments and distribute them all over your file...
The notebooks I saw so far are linear, single language and don't do the weaving (shuffle and embed the code chunks into full files)
For their purpose, incrementally derive some computation and data analysis, that's fine. For describing a complex system to both a human reader and a machine, in that order, that would not be enough.
It occurs to me that the root of the problem is that we have competing motivations. On the one side you have the desire to have well documented code, maximizing the benefit to those reading/studying it. On the other side you have the desire to get the most coding done in the least amount of time (something you can push to production, that correctly implements some task or purpose).
Both of these motivations are valid and good. The hard part is knowing at what level of each do we get the best balance of the two.
In one the situation, the "novel" analogy would be appropriate. For instance, I would be very interested in detailed explanations of something like PostgreSQL. A well-written book by someone (or "someones") with intimate knowledge of that code could be tremendously valuable. Here I have in mind something that actually walks through parts of the code, in a literate programming style.
On the other hand, maybe you don't want that much detail, but you still want some understanding of the code in order to do a small task - in that vein, something of the 'car manual' variety would be more appropriate.
I can imagine a full spectrum, from a multi-volume Knuth-like set to something on the order of a single-page cheat sheet. The problem is, it always comes down to how much time do you have to accomplish what you need to accomplish, and how much time will those writing the checks allow you to make informed choices on how things are documented (which, unfortunately, is all too often, ZERO).
