> Literate programming fails because it I'm a programmer and so it is telling things I already know.
Code is just a medium. You’re supposed to know it. What you don’t know is the domain knowledge the code is solving, and that’s what’s written in the literate program, along with diagrams, math, etc to aid your understanding.
Look again at the examples - very often it isn't that at all. My example - where Knuth himself wrote about "#include <stdio.h>" proves my point. If you don't know what stdio.h is about you are not competent to be reading this code in the first place.
> What you don’t know is the domain knowledge the code is solving
THIS IS UTTERLY FALSE! The company hired me to work on this code and trained me. Or I got interested in the problem and learned the domain knowledge already. If you don't have this basic knowledge you either won't read the code in the first place, or you can only make the most minimal basic contributions for the next few months while learning it. Unless this problem is very trivial there are lots of other source files and lots of other knowledge needed that is outside the scope of the current file.
Write comments to remind the experts (which is you in 6 months!) of the tricky details that they dare not forget. Write comments to explain to people who are experts in a different area of your program who this works - but you can assume a lot of shared domain knowledge because they work on the same project.
So you can read a section of code and immediately know what it’s doing and why it’s written that way? And the decisions and context that led to it? And you have no further questions?
furthmore you are familiar with all techniques your coworkers might employ?
Wow!
> Write comments to remind the experts
What if I want images in comments or a math formula? What if want to refer to another section of code?
> So you can read a section of code and immediately know what it’s doing and why it’s written that way?
No, but the documentation you have been advocating (at least so far here) wouldn't help either.
> What if I want images in comments or a math formula?
I don't have a good answer. I've seen some interesting ascii art. It looked cool, but it was out of date from what the code did and so needed to be deleted as I'm not enough of an artist to fix it.
> What if want to refer to another section of code? Use your IDE to go to the definition of the code in question, (hopefuly you can do this).
I understand (or think I understand) your problem. I often have problems with code that I don't understand. I don't think literate programming helps though as nobody actually is writing documentation of the type that would answer the questions I really have.
> nobody actually is writing documentation of the type that would answer the questions I really have.
That’s a choice though, right? The tools enable you to document in ways you haven’t before.
The most valuable use case I have seen is code that’s not too long and is read a lot of times. That’s when getting every decision, diagram, etc in one place helps a lot of people.
I have one particular case at work where every line of code has had several meetings about it to ensure the parameters are correct, etc.
Code is just a medium. You’re supposed to know it. What you don’t know is the domain knowledge the code is solving, and that’s what’s written in the literate program, along with diagrams, math, etc to aid your understanding.