Literate programming is excellent for both explanation and documentation. Not only are the various code blocks explained and documented, they contain the actual sources used to build the program.<p>Think of source code like equations in a physics textbook. Mostly, when you need a documentation you read the surrounding paragraphs. When you need an explanation you read the whole chapter.<p>We need to drag programming out of the punched-card era.