@nikitonsky good article.

About adding the diagrams, nice idea.
Emacs can sort of do that via easydraw: https://github.com/misohena/el-easydraw/

It's a full blown diagram editor.
But I guess the down side is that it's not cross-editor supported.