John D. Cook has another post in his series of posts discussing the use of Org mode in his professional duties as a consulting mathematician. This time he discusses the pros and cons of literate programming.
He recounts the story of a blog post that had some errors that he believes might have been avoided if he’d used literate programming. He rewrote the post using literate programming and had a few observations.
First, he found that it was harder to compose the post using literate programming. There’s a lot of little markup details that you have to deal with that aren’t necessary when you just paste in a value from a separate computation. Still, that effort pays dividends if you have to update your post with new parameters and can help reduce errors.
I’ve reached the point where I do all my writing in Org-mode and always do any necessary computations in a code block. It’s a real win because if parameters change I just need to change it in one place and regenerate the document and I don’t need to worry about errors induced by pasting in values.
Take a look at Cook’s post for the point of view of someone who, although technical, is not really part of the developer community.