As everyone around here knows, I am a big fan of reproducible research and the idea of including data, code, and explanatory text in the same file. For researchers, that makes it easy for others to verify and extend the results but it’s also a great way for others to explain some process and embed the code to implement it in a single file.
Norman Walsh has a short post that explores these ideas by using the Org-mode Babel functionality. His example involves calculating the Fibonacci sequence. There’s some explanatory text—more of a place holder, really—and then some code to implement the calculation. The nice thing about Babel, of course, is that you can actually execute that code and place the result right in your document. As Mike Hamrick has explained, that makes it easy to keep the results consistent with the data as it evolves.
If you’re writing explanatory material that involves code samples, I know of no better way than using Org mode. You get consistent documents that can be exported to HTML, PDF, and many other formats. Take a look at Walsh’s post and Hamrick’s video to see this in action.
I know I flog this idea a lot but it’s such a powerful method that I’m always amazed by it. If you do research or write explanatory material, you really should consider the Org mode/Babel/reproducible research approach.