Zed Shaw completely misses the point about, Literate Programming. He says that you should have your english and your code in two separate files, and then combine them with a compiler. This is exactly wrong, you want your description of the algorithm right next to the algorithm itself, so that the two don't diverge when you change your code.
When I program, I think about the story that I want to tell, and then I write a small outline or paragraph about what I how I want the code to tell the story, then I write the code, and then I write more documentation about the code.
It would be really nice though if I could just hide the story like collapsing an outline in Emacs, so that I could focus on just the code when I want, or just the documentation, but having the two in different files is just wrong.
