> This is a nice run through of some pitfalls. I'd love to see an accompanying "how to make a great architecture diagram", I think the purpose behind these diagrams often gets lost (or was bad to start with) and as a result I've seen (and probably produced) a lot of unhelpful architecture diagrams.

Naturally I think you'd go a long way just avoiding these pitfalls and doing the reverse (e.g. label your arrows). For a somewhat different perspective on making good diagrams by reducing their complexity, I wrote on this just last month:

[0] https://www.ilograph.com/blog/posts/breaking-up-the-master-d...