There are notable exceptions. In scientific programming, code is tightly linked to scientific context and explaining stuff in prose is vital for being able to u

There are notable exceptions. In scientific programming, code is tightly linked to scientific context and explaining stuff in prose is vital for being able to understand. Often, people claiming their code just reads itself just haven't worked on hard enough problems. Other than that, people seem to mistake the reason for having documentation: we aren't necessarily (just) explaining how something works, rather why you made a certain choice, why the alternative doesn't work etc. Yes, writing a good literate program is more work, and it may not be for everything, but there are many cases where this approach can help communicating your work and save time in the process. That being said, I'm not a huge fan of Org-mode, since it forces Emacs onto your collaborators. A much nicer method based on Markdown is Entangled: https://entangled.github.io/ https://entangled.github.io/, though disclaimer: I'm the author of Entangled ;)