Hm... good software architecture is always clear and usually simple. So I think the title here is self-contradictory. I do agree with usually using custom diag

Hm... good software architecture is always clear and usually simple. So I think the title here is self-contradictory. I do agree with usually using custom diagrams rather than, e.g., UML ones. Diagrams need to communicate. The problem with the formally defined ones is that they communicate what they are specified to communicate, not what you need to communicate. As a result you end up with perhaps multiple diagrams to cover the concept, or you need to add text or an ill-fitting custom overlay or custom exceptions, etc. Also, people who don’t create these diagrams regularly (a large part of your intended audience) have trouble remembering all the intricacies of the diagram language, so important concepts are made obscure rather than clear. Anyway, you want to be focused on communicating certain concepts, not building a correct diagram.