The first comment, written by none other than Peter Norvig, is also worth reading.
EDIT: link - http://www.johndcook.com/blog/2016/07/06/literate-programmin...
EDIT: link - http://www.johndcook.com/blog/2016/07/06/literate-programmin...
The worst program I've ever had to maintain was written in funnelweb. It was a large, complicated program, so the funnelweb-generated documentation was tens of thousands of pages long. Nobody was ever going to read that. Trying to find out what you needed to modify to fix a bug was impossible from that document. Most developers I know looked at the woven C code (after all, that's where the line numbers in the stack trace pointed to), and worked from there.