Software engineers, testers or product managers use mental models to reason about the systems they work with.
These different roles use architecture diagrams to build their own mental models.
People will make assumptions based on their understanding. And how you craft these diagrams will have a tremendous impact on the correctness of the assumptions.
Architecture diagrams are like text documents. It’s easy to create one. But it’s hard to create a good one. I would argue that for technical documentation, diagrams are even more difficult.
Drawing boxes and arrows is easy.
Sketching out the boxes and arrows is the easy part to put down on paper. The arrangement of these notations and the contents they represent is much harder to convey to the reader.
How do you make sure the reader will understand it as you do?