I think Knuth is just plain wrong - documentation and code should be separate things with different aims and requirements.
It's one thing to include some background notes around a single algorithm, it's something else entirely to document an entire application.
The missing link is the lack of meta-representation and abstraction tools.
Text is very poor way to show relationships, and most code is more like a tree structure. IDEs have gotten better at representing this, but they still tend to show text files as primary and relationships as secondary.
More text in/around the text files is definitely not the answer. Structural representations - dynamic useful ones, not bureaucratic nonsense like UML - and smarter searching and filtering are more likely to be helpful, with associated text descriptions for key concepts.
I think you’re right, especially when you look at the kind of silliness he’s actually writing. It’s just overcommented code, and worse than that, trying to be cute. Sorry, massive respect for the guy and his accomplishments, but this is not a good idea.
It's one thing to include some background notes around a single algorithm, it's something else entirely to document an entire application.
The missing link is the lack of meta-representation and abstraction tools.
Text is very poor way to show relationships, and most code is more like a tree structure. IDEs have gotten better at representing this, but they still tend to show text files as primary and relationships as secondary.
More text in/around the text files is definitely not the answer. Structural representations - dynamic useful ones, not bureaucratic nonsense like UML - and smarter searching and filtering are more likely to be helpful, with associated text descriptions for key concepts.