Solid piece on literate programming by Richard Gall for The New Stack. My foremost exposure to the practice came from Jeremy Ashkenas’ CoffeeScript and Backbone.js docs. I always found it cool and useful to read, but couldn’t imagine myself writing code/docs that way. Which brings us to this bit at the end of the article:

“One of the things we learned is that it’s very expensive,” he said. “And so you spend time trying to figure out what sort of situations justify the expense. And one of them is where people are building relatively small, sophisticated kernels that are going to be shared widely.”

Seems like Jeremy’s use case drilled it. If you’re mostly writing application code, literate programming probably isn’t worth the headache, but for library/framework authors…