Almost all of the source code for Axiom (1.2 million lines of code) lives inside latex documents. They are literate programs. I can explain the most complex ideas along with the code that implements them. And I can illustrate the ideas using images, diagrams, and figures.
In this video [0] by Howard Abrahams you can see how to wave the instructions and the execution of them with Emacs.
Another advantage is that you can mix your diagrams (in plantuml or ASCII art) with your code, in the same org-mode file.
Gitub displays .org files the same way it does Markdown.