We agree - useful, accurate, and up to date docs are what increases trust! We're bringing docs closer to the diagrams to visually explain your system in smaller chunks. We've found docs often accompany diagrams, and they become out of date as soon as they're exported! We think instead of diagrams being in docs, docs should be in the diagram.

Alternatively, they can live together.

For example, I ended up writing this to integrate diagrams and Sphinx. https://github.com/j-martin/sphinx-diagrams

Similarly there's https://pypi.org/project/sphinxcontrib-plantuml/ and https://mermaid-js.github.io/mermaid/#/ (among other similar tools).

Eventually your docs will be updated and noone will be around to update the included diagrams. And when the users (the developers!) notice the discrepancy, trust will decrease.