笔记：The Art of Crafting Architectural Diagrams

讲如何画好架构图，写的不错，平时需要写方案、做架构的人正好可以借鉴一下。

Key Takeaways
Designing architectural diagrams might not be an easy task; it can be tricky or error prone, even for the simplest ones. Creating consistent and meaningful diagrams brings clarity and consensus across different stakeholders.
In most cases, the real issues are not strictly related to using a less efficient Architectural Description Language (e.g. UML), but the misunderstanding of diagrams importance, relying on improper or inconsistent guidelines or even the lack of architectural education.
In the process of creating diagrams, try to blend automatically generated with manually created ones in order to minimize the work, to illustrate different set of concerns and to cover multiple abstraction levels of the system.
As the system is evolving, maintaining diagrams up-to-date requires extra effort. We need to know how to efficiently proceed in such cases by still keeping consistency and robustness across architectural diagrams.
Modern architectures bring extra complexities which are reflected in the diagrams. Additional concerns might emerge and could easily

然后以下图为例，讲了不好的架构图的问题：

以下是以那张图为例说的架构图中常见的问题（说实话虽然我一开始看那张图也觉得有些问题，不过没有想到他能列这么多）：
What does a box or shape denote?
What do different edges of a shape represent?
What does a line or an arrow denote?
What is the communication/association type indicated by a line or arrow?
What does that color mean?
Missing relationships between diagram elements or isolated entities
Misleading/undocumented acronyms or too vague/generic terms
Emphasize technologies, frameworks, programming or scripting languages, IDE or development methodology on diagrams
Mix runtime and static elements in the same diagram
Make assumptions like "I will verbally describe this", and "I will explain it later"
Conflicting levels of details or mixed abstractions
Cluttered or too vague diagrams trying to show too much or insufficient level of detail

然后是画架构图的建议：
Choose the optimal number of diagrams
Keep structural and semantical consistency across diagrams
Prevent diagrams fragmentation
Keep traceability across diagrams
Add legends next to architectural diagrams

然后是对一些问题的探讨：
1，Does the Architectural Description Language (e.g. UML, ArchiMate, etc.) make a difference?这部分感觉没有说什么太有用的。
2，How can diagrams be kept up-to-date as the system is developed, and changes to the architecture materialize。
这个他提了三条：
first option, and the easiest one, would be to automatically generate diagrams out of the source code, which is the ground truth.
The second approach would be to first design the diagrams using a dedicated tool which then generate the source code skeletons (e.g. components/packages with boundaries, APIs) used later on by developers to fill in the code.
The last case involves manually updating the diagrams every time a new feature - which has an impact on the architectural design - is implemented.
Taking into account existing tools, my recommendation is to have a mix; to blend automatically and manually create diagrams.
3，What complications (or simplifications) emerge for architectural diagrams when dealing with modern architectures (e.g. microservices)?
这个感觉也米有说太多有用的。

原文链接：https://www.infoq.com/articles/crafting-architectural-diagrams