ACM Queue has a (posthumous) article by Jef Raskin on documentation. He wraps up by saying:
Prior, clear, and extensive documentation is a key element in creating software that can survive and adapt. Documenting to high standards will decrease development time, result in better work, and improve the bottom line. Its hard to ask for more than that from any technique.
I might add to this: The problem with literate programming is that so few programmers are really literate. Before you fly off the handle: many, many engineers are smart and clearly have passed the hurdles of college exams and such, but if you intersect programmers with the ability to write well, and the desire to write well, you wind up with a very small subset indeed.
Then again, at 3am my tolerance for horsepucky is low indeed, leading to things like
and no further apologies. On the other other hand, maybe this is as expressive as documentation ever gets. 🙂