I continue to struggle with the writing of Notebooks that are "literate". I think Knuth had a great idea when he proposed "Literate Programming" but it got side-tracked, in my opinion, with the macro-expansion implementation.
My main problem is that Mathematica best practices seem to dictate use of functional programming - and, in general, I like this idea very much. The resulting problem is that the best way to develop functional programming solutions seems to be to design and implement things bottom-up and inside-out. (I've seen Wolfram personnel do this in Webcasts and I've had a conversation with a Support staffer about this very point.)
While the resulting code is compact, and - assuming it fits in main memory - very fast, it is also (to me) very difficult to understand later. Notions such as abstraction, information hiding, and the lot, don't seem to have a place in this paradigm.
For example, arguments critical to understanding what a function does can be "far" away from the invocation of the function making it hard to "grok" things conceptually.
So, I write prose to try to describe how whatever I wrote works, and, often, why I did it the way I did. I do this so I can come back later and understand what I did.
To me, "Literate Programming" is about capturing much of the thought process that went into the development of the code.
If I were a better mathematician I might be able to make my solutions "read" more like math, but I've been unable to do this.