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.

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.