Literate programming is an interesting approach. I wonder if it is really helpful for building large systems though.
In my opinion, trying to understand a large codebase is a learning activity. True, documentation is important at times. However, it depends also on the author. If writing good code is hard, writing good literate programs is imho harder. Now one needs to be a good writer and a good coder. Probably the skills are transferable to an extent, but I think they are different things in the end.
Besides that, the ability to explore and try things out is also helpful for learning things. That's why I think Smalltalk is the most approachable language so far. You get a browser and a REPL (workspace), and the object explorer plus inspector tools. Not to mention the method finder. All these tools to let you learn how code works. I really miss having some of these tools in other languages, especially the browser. Even Lisp doesn't have that one afaik (correct me if I'm wrong).
In the end, I believe language facilities such as the ones I previously mentioned are more valuable to understanding than being able to wrap code in prose. Still, documentation is invaluable at times. So comments will (should) never go away.
There are notable exceptions. In scientific programming, code is tightly linked to scientific context and explaining stuff in prose is vital for being able to understand. Often, people claiming their code just reads itself just haven't worked on hard enough problems. Other than that, people seem to mistake the reason for having documentation: we aren't necessarily (just) explaining how something works, rather why you made a certain choice, why the alternative doesn't work etc.
Yes, writing a good literate program is more work, and it may not be for everything, but there are many cases where this approach can help communicating your work and save time in the process.
That being said, I'm not a huge fan of Org-mode, since it forces Emacs onto your collaborators. A much nicer method based on Markdown is Entangled: https://entangled.github.io/, though disclaimer: I'm the author of Entangled ;)
Literate programming shouldnt necessarily apply to application code for large systems but I almost always want more literate tests that clearly explain not just what should happen under all kinds of scenarios but why it does that. Even better if I had hyperlinked explanations for domain specific terms.
If I always had this I think I'd become fully productive on large systems 2x as quickly.
I dont think this need be achieved by hiring a unicorn coder who is also a great writer but by making tests more accessible and editable by good technical writers so that both parties can collaborate around behavioral tests that double as documentation.
In my opinion, trying to understand a large codebase is a learning activity. True, documentation is important at times. However, it depends also on the author. If writing good code is hard, writing good literate programs is imho harder. Now one needs to be a good writer and a good coder. Probably the skills are transferable to an extent, but I think they are different things in the end.
Besides that, the ability to explore and try things out is also helpful for learning things. That's why I think Smalltalk is the most approachable language so far. You get a browser and a REPL (workspace), and the object explorer plus inspector tools. Not to mention the method finder. All these tools to let you learn how code works. I really miss having some of these tools in other languages, especially the browser. Even Lisp doesn't have that one afaik (correct me if I'm wrong).
In the end, I believe language facilities such as the ones I previously mentioned are more valuable to understanding than being able to wrap code in prose. Still, documentation is invaluable at times. So comments will (should) never go away.