I agree with most of your ideas, and I usually apply them myself. But wanted to ask about graphics and charts, do you use any specific tool? They can be time-consuming to get right and update.
Also, I believe a problem here is that on large organizations and codebases many programmers don't really understand themselves the relationships/interactions between systems, or people setting the standards think overviews are hard to standardize, or they think other people think documentation is a pain to write so they try to minimize the work needed to get it "right".
EDIT: came up with a better way to put it: documentation should deal with what a system does, why and where, then how it achieves so in a broad sense, and finally deal with the implementation details (which is the only part we are kinda handling nowadays, as you explained).
Also, I believe a problem here is that on large organizations and codebases many programmers don't really understand themselves the relationships/interactions between systems, or people setting the standards think overviews are hard to standardize, or they think other people think documentation is a pain to write so they try to minimize the work needed to get it "right".
EDIT: came up with a better way to put it: documentation should deal with what a system does, why and where, then how it achieves so in a broad sense, and finally deal with the implementation details (which is the only part we are kinda handling nowadays, as you explained).