I always liked the idea of literate programming, but it never seemed to get a toe in the door.
A good start would be just commenting code! Almost all the code I've looked into recently has been startling - the only comments are the licence boilerplate at the top of each file!
I can think of only one product/library/package that was commented to explain what was happening. Go look at the source for a random package that you depend on. If you're really lucky, there might be something hinting at the meaning of function arguments, but like as not, not even that ;(
replies(1):