关键要点
通过创建和维护模式映射来提供准确且有价值的内容并不容易。 在大多数情况下，由于无法准确确定文档的收件人和实际需求，因此创建了太多、太多或没有关联的文档。
我们经常犯的最大错误之一是绘制系统高度波动部分的详细体系结构图。 除非是自动生成的，否则手动维护对我们来说是个负担。
实际上，大多数利益相关者对详细的体系结构图不感兴趣，但对反映系统模块和边界的一个或两个高级体系结构图感兴趣。 此外，要深入了解系统，代码是事实的来源，但通常只有开发人员对代码感兴趣。
为了创建具有一定质量的体系结构图，可以进行头脑风暴，并与团队就什么对他们真正有用达成一致。 不要根据源代码中的明显内容或模式方法创建模式映射。
体系结构图的主要目的应该是促进合作、加强交流，并提供愿景和指导。
在墙上创建一两个高级体系结构图，并在会议(例如车站会议)期间使用它们。 作为架构师，你应该让它们可视化，变得有价值，成为项目文化的一部分。 请不要隐藏这些，也不要放在相关人员难以接触的地方。
尝试通过创建模式映射作为技术文档的一部分来反映APP应用程序的内部状态，但在许多情况下是不正确的。 由此生成的体系结构图可能非常全面，也可能非常模糊。 在某些情况下，模式映射完全无关。 以前，我写了几个关于如何创建有用的模式图的技巧。
即使创建了相关的模式映射，也很少作为持续开发过程的一部分进行更新。 实际上，您只需偶尔更新文档，它可能在某些sprint期间(如果您有时间更新文档)或在发布特定版本之前。 另一方面，大多数开发人员(参加我的软件体系结构课程的同事和学生)不赞成编写和维护技术文档。 他们认为这些任务枯燥、费时，而且价值低于其他任务。 我们甚至认为，只要源代码写得足够好，就不需要文档。 虽然有例外，但我确信对于大多数项目，模式映射是相同的。
我们做错了什么，以及如何改进，首先，最重要的是要了解谁是架构图和技术文档的真正受益者文档的数量和质量必须反映相关人员的需求。 因为只有这样，才能制作正确合适的文档。
主要受益者应该是直接参与项目的团队（开发人员、测试工程师、业务分析师、DevOps工程师，等等）根据我的经验，在团队之外，相关人员很少真正关注文档。 在最好的情况下，您可能会对一个或两个高级体系结构图(如上下文图、APP应用程序或软件组件图)感兴趣，后者可以大致描述系统结构并提供高级系统视图。
但是，在很多情况下，我们没有确定真正的受益者及其真正的需求，而是直接制作了过多的文档。 这些文档很快就会成为维护的负担，很快就会过时。 在其他情况下，因为没有时间、不感兴趣或者没有人愿意承担这个任务，所以直接省略了模式映射。 此外，敏捷宣言主张团队应该更加重视软件本身，而不是文档。 这意味着不鼓励繁琐的文档处理过程。
为了平衡合适的文档级别，请团队试试。
询问每个同事，文档需要提供什么内容，以及需要包括什么类型的模式映射。 收集他们的意见，进行集体讨论，就团队真正需要的东西达成一致。 队伍之外可能有一两个有影响力的相关人员。 他们提出了额外的需求，架构师也有责任考虑到这种需求。 在此基础上，制定相应数量和质量的技术文件，以满足相关人员的需求。 如果开发人员了解文档的真正价值，并对剩余价值感兴趣，他们可以参与文档的更新和维护。 最后，每个人都会开心起来。 但是，如果他们不理解文档的必要性，或者他们不介意，几乎可以忽略。 因为一个人(架构师)很难维护文档。 这应该是团队成员的共同责任。
以前，瀑布式项目采用了综合的企业体系结构方法，或者是象牙塔设计师提出的要求，导致文档过多。 当软件项目开始大规模接受敏捷时，一个常见的误解是人们认为文档是不必要的，因为软件比文档更重要。 当然，这是两个极端的情况。 没有确切的方法或科学过程来明确指定项目所需的文档数量。 目前的软件体系结构方法都是纯粹的建议或指导原则。 过去遵循的综合体系结构过程在当前项目中已经大大简化，不再存在。 这并不是说要创建更少的文档，或者根本不创建文档，而是意味着需要专注于创建具有真正价值的文档，而不干扰团队的进展。 此外，并不是所有的文档都提供价值。 但是，这并不等于“所有文档都没有价值”。 此外，根据经济、政治等环境、业务目标和利益相关者等因素，对一个项目有意义的文档可能对另一个项目没那么有用。
在这种情况下，很难得出这个问题的正确答案。 被称为模式映射的文档数量合适吗？ 最后，它关系到每个项目和设计师的经验，可以说是“视情况而定”。 能够适当提供价值的文档数量取决于团队需要什么。 我的建议是确定需要与团队一起编写的技术文档数量，无论这对团队意味着什么。 如果文档对你的项目来说没有意义(为什么会这样？ 这个也可以接受。 记录小组作出的决定，并告知所有利益攸关方。 如果2、3个模式映射有用，请随时更新，以保持一致并始终反映系统状态。 不要专注于不会带来价值的事情。
那么，用架子吧
构图来做什么？一般而言，架构图和文档应该主要用于团队内部和团队之间的协作、沟通、愿景和指导。它们还应该包含项目的重要设计决策（在某个特定时刻采取）。
架构图应该帮助每个人看到大局，了解周围的环境。在我看来，这应该是创建和维护架构图背后的根本原因。
例如，上下文架构图完全满足了这种需求，并提供了关于系统边界的大量细节，从而可以看到全局。它有助于团队在不同的利益相关者之间达成共识，并简化沟通。我参加了很多会议，当大屏幕上出现这样的上下文架构图时，省去了很多问题，并消除了关于高级系统架构的不确定性。
不过，我们经常会尝试创建综合性的文档来反映系统的内部状态，它们可以是状态图、活动图、类图、实体图、并发图等形式。但这些很快就会过时，除非它们是基于源代码通过一些“神奇”的工具自动生成的。
如果人们不需要它们，那么创建这些详细的架构图有什么意义呢？业务利益相关者的抽象图绰绰有余了。在大多数情况下，对于开发人员来说，源代码（即单一事实来源）才是他们真正需要的。因此，请停止为代码中自解释的内容创建详细的架构图，或者当没有真正受众时。
因此，创建有意义的小型架构图，并将它们加到技术文档中。对于大多数应用程序，可能需要两三种架构图。最常见的是上下文图、组件图、系统图或部署图。
我的真实项目示例在我的项目中，我主要使用两种类型的架构图：
上下文图 应用程序或软件组件图请将这些图视为简单的示例，主要作为每种图应该提供哪些合理信息的指导。图中的信息应该与相应的抽象级别相关，还必须满足利益相关者的需求。
在实践中，你可能倾向于向图中添加越来越多的细节，但是如果它们对利益相关者没有真正的用处，就会导致额外的噪音，增加维护成本，而且容易过时。这些图中的一些细节，例如协议和数据格式，可能对技术利益相关者来说比较方便，因为它们是必要的实现细节。然而，正如之前所述，并不存在精确的方法来确定图中包含多少数量的细节才算是恰当的，这完全取决于不同的项目。不过，架构师需要知道对利益相关者来说真正有用的是什么，并创建和维护架构图来正确地反映这一点。
除了这些架构图之外的任何额外细节，我可以在源代码中找到，或者通过某些工具自动生成（例如运行时视图、开发视图、系统或基础设施视图等）。
我还在会议室中绘制软件架构图（包括所有应用程序组件）。在我们的站会和其他会议期间，人们边指着墙上的这些架构图边谈论他们的任务、状态和遇到的问题。这样，每个团队成员，从产品所有者到开发人员，都能理解系统的全局，并预见到整体障碍和其他集成挑战。除此之外，在Sprint期间，它还为整个团队提供了更准确的进度状态，尤其是在分布式架构中，且人与人之间存在依赖关系时。
我建议你也在团队中这么做。通过使用足够的架构图继续加强协作、沟通、愿景和指导，否则就不要创建它们，特别是如果团队不使用它们的话。在大多数情况下，手动创建和维护架构图，以此来反映代码行为纯粹是在浪费时间。如果你这样做了，随着源代码的演变，你可能会想要添加越来越多这样的架构图，这是一个危险的陷阱。与其创建大量令人精疲力尽的架构图，不如坚持使用两到三个从不同抽象层次描述系统的架构图，这对于团队来说是非常必要的。经常性地更新它们，如果这个任务不包含太多的细节，并且是团队文化的一部分，那么它将变得更容易。
另外，请记住，团队应该是架构图的主要受益者。如果它们没有表现出任何兴趣，那么你应该停止创建它们，因为这可能是在浪费时间。我们不应该只是“为了拥有它们”，或者为了遵循综合性的架构方法，或者纯粹为了证明我们作为架构师的角色而去创建架构图。
关于作者
Ionut Balosin是Luxoft的软件架构师，在各种商业应用程序方面拥有超过10年的经验，热衷于性能和调优以及软件架构。他经常在各种技术大会上发表演讲，是一个技术培训师。
查看英文原文：
https://www.infoq.com/articles/why-architectural-diagrams