敏捷团队更好的架构图：可行的提示和课程

软件工程师，测试人员或产品经理使用精神模型来推理他们使用的系统。这些不同的角色使用架构图来构建自己的心理模型。人们将根据他们的理解做出假设。以及如何制作这些图表将对假设的正确性产生巨大影响。

架构图都像文本文档。它很容易创建一个。但是很难创造一个好的。我争辩说，对于技术文件，图表更加困难。

勾勒出他的盒子和箭是放在纸上的容易部分。这些符号的布置和它们所代表的内容更难传达给读者。您如何确保读者会在您做到这一点？

要回答这个问题，我们需要询问自己为什么我们创建架构图。这将推动我们来列出我们希望通过这些图表实现的各种目标。我们将确定要牢记的主要限制，以达到这些目标，真实的任何图表和任何受众。

一旦您了解目标和约束，我们将更容易记住我们将展示的少数共同指导原则来帮助您实现这些目标。

最常见的用例，以及我们在此覆盖的唯一一个，是用于在人类之间传输知识的图。

我们可以为许多不同的目的使用它们：记录组件交互，数据流，如何部署的情况，如何在现有系统中发生任何展示的事情，或者在现有系统中发生一些计划的更改。该图可能是集合的一部分。它可能会创建以帮助决策，或者它用于最终确定设计决策，然后将开发人员或其与开发团队之间的共享工件进行帮助，以帮助文档。

最终，它只以紧凑的方式将信息转移给别人。紧凑的方面很重要：如果读者需要大量的文本来了解图表，或者如果您需要个人解释图，则这些是该图需要改进的强信号。

红旗：如果读者需要重大解释，写入或说话，以了解图表，您需要提高或简化它。

您 - 任何其他个人 - 构建一个精神模型到一个系统的理由。考虑抽象的东西是我们的原料。

«随着系统的复杂性增加，该系统的任何代理模型的准确性都会降低。 » - David Dr.

无论您在文档和图表中投入多少努力，其他人都将建立一个系统的精神模型，这将与您的不同。实际上，您自己的系统模型可能与您几周或几个月前的系统不同。它将来会有所不同。

心理模型是一种模型：它根据定义是不完美的，但它是一个有用的工具，原因是系统。

«请记住，您的平台是您的用户的神奇黑匣子。你不能指望他们在没有反馈循环和丰富的心理模型的情况下合理行事。帮助他们出来 - 特别是您的超级用户。如果您可以帮助他们自助，它会节省您的时间。 » - 慈善专业专业第4平台诫命。 （SRC：十平台诫命）

您的目标不是帮助人们构建一个模型，这将尽可能接近您的模型。您的使命是帮助他们建立一个良好的心理模型。

在这里，我们发现两种不同的方法来符合在这种背景下的“好”意味着什么。

人们可以帮助他们建立一个允许他们完成工作的心理模型，这也可靠地思考系统。

共同点：“相关的相互知识，相互信仰，以及支持一些联合活动中相互依存行动的相互假设。” - 赫伯特克拉克

这两个目标通常重叠，但有时你只针对其中一个，例如，建立一个高级图，让人们了解系统。仍然，他们可能永远不会直接与之互动。这与创建图表以帮助运算符排除系统进行故障排除时非常不同。

人们根据他们将与其现有的系统知识相结合的信息收集信息的信息来构建他们的心理模型。他们通过文档和随着时间的推移通过他们的互动来收集这些其他知识。

人们使用系统的不同部分，以及不同的水平。所以这完全没问题，只要它没有错。它并不完美，也不准确，但它需要没有错。

Richard Court在他的“在Cyclone的中心工作”谈话中，慢慢地建造下图来说明不同的角色建立自己的心理模型，与其他人创造的那些不同，从他们与系统的互动中不同。没有人确切地知道系统的内部状态。我们都从我们观察和学习的系统中推断出来。这里的关键是这些模型不需要完成。他们需要对任务进行足够的准确性。

虽然它听起来更加工作（是的，是的，但它是），它实际上是有用的，因为它有助于很多在定义范围内。

这个是显而易见的，但经常被忽视。如果观众是技术团队已经了解了很多关于现有系统，你可以承担很多。在频谱的另一侧，项目外部的人 - 甚至是域名 - 甚至有更少的先验知识。

一个关键的想法是您在内部文档，onboard文档或将项目呈现给外部合作伙伴/客户端的图表应该非常不同。如果您发现自己重新使用一个图表进行不同的受众，请停止并思考一下，如果他们拥有所有先前的知识来理解该图。有时它足够接近完成这项工作。有时，两个预期的受众之间存在鸿沟，您应该建立一个新的鸿沟，或者只是跳过它。

关键主意：明确地了解目标受众。考虑他们的关于系统和域的先验知识。如果您不确定可以授予的东西，您需要记录它。

即使您定位单个配置文件，此人也有可能有关系统的不同目标。如果您为多个配置文件创建此项，这变得更有可能。

您的主要目标可能是分享有关组件依赖性的知识。或者分享有关数据流和组件之间的交互的知识。或者您可能希望突出显示要修复某些问题所需的更改，这意味着删除一些东西，以及新的东西并更改其他部分。

列表继续，但你得到了这个想法。有一个主要的意图。嗯，应该只有一个主要的意图。它可以在应用程序组件上，集成流程，如何部署它，它与...互动的组件

如果您正在研究的图表正在尝试立即传达几个目标，这是一个指标，您应该将其分成多个图表。

关键主意：定义一个目标。如果要记录多个目标，请创建多个图表。

这个目标将定义重点。您需要将某个地方专注于帮助读者理解他们应该引导他们的注意力并投入大脑周期。

您可以将焦点设置在单个组件上，或者在共享要突出显示的公共属性的组件的子集上，或者在流程中。

您的焦点可以是共享由许多步骤组成的特定流程的细节，并涉及多个组件。当您使用步骤1的注释时，您通常会发现自己创建此项，...有时，“框和箭头”图更容易掌握的东西，而不是传统的序列图（或支持它）。这是你的重点。

创建图表以记录某些迁移或更新时，将焦点设置在共享属性上很大。现在，您的焦点是在不断变化的部分上：您将删除哪些，您将添加哪些，您将要更改（并且所有其他人都保持不变）。

为什么了解和清楚你的重点是重要的？因为它可以使您能够过滤掉其不支持它的任何东西。它是您可以使用的关键过滤器来删除杂乱。

对于图中的任何东西，你可以 - 而且应该 - 问自己：如果我删除了这一点，它会改变人们如何理解重点的想法？如果答案是否定，请将其删除！

删除东西。简化图表直接降低了读取器的认知负载。它对图表的更容易理解有多少直接影响。

关键主意：将重点放在支持您的目标的主要内容上，并删除任何不支持这种焦点的东西。

在C4世界中，这通常如下：通过绘制设置焦点的碎片来开始图表。然后，您需要记录其连接或关系，以便导致他们的直接“邻居”。通常，您应该停止在此添加内容。您可以优化现有的东西，查看/添加注释，传说，但如果您以这种方式构建，您更有可能不会将混乱添加到您的图表中。

图的寿命是焦点的另一个关键部分。您应该使其明确到读者。写下来。

读者应该知道时间何时，他们看的图表是准确的。我们都知道文档从现实中漂移。您是否记录它会看起来像，它曾经是什么样的或现在就像它一样？

如果您只描述瞬态状态，例如，相对于某些系统演进或迁移的更新，则使其对读者非常明显。

关键主意：记录图表的有效时间框架。当它准确时，直到它应该仍然准确。

但为什么这个强制性？为什么我们不能与一切创建一个巨大的图表？这一切都归结为读者的认知负荷。这也是为什么观众的先验知识如此重要。

这篇文章不会深入了解认知负荷，但让我们回顾我们需要的主要想法。

我们的工作内存容量非常有限。我们可以在给定时间保持在我们的工作记忆中的七个项目。七加或减去两个是我们在文献中看到的共同范围。

这就是为什么要将信息量限制为进程到最相关的原因，以使最相关的东西易于转移。

当您看到4个垂直线路时，您不会仔细跟踪它们，即时查看矩形。相同的是字母的形状，如您阅读：您不必分析字母的形状以识别它们。这句话也是如此。如果缺少一封信，你的大脑会自动理解并纠正它。当您阅读您不熟悉的外语时，您意识到该分块机制如何高效。甚至更多，所以当你读出一个外出的字母表时，你不熟悉（例如，日语或中国人，如果你从未学过它）。

这很有意思，但它也是有用的知识，我们可以利用，使我们的图更容易阅读。这里的课程是重新使用常见的习语和读者将熟悉的模式。他们已经学会了块。这意味着阅读和理解该图将更容易。

如果您的域具有常见的形状和图标，请使用它们！你可能会相信他们有缺陷，他们并不完美，可能是这种情况。但是，如果读者更容易理解你的图表，因为他已经知道这些形状和图标的含义，这会产生显着差异！不仅您的图更容易理解，而且因为它对读者的认知负荷施加了更少的压力，它也不太容易出错。

共享标准的大示例是数据流程图或流程图。他们已经拥有普遍的成语，如流程图中的问题/选择的钻石。对于数据流程图，yourdon和coad，或gane和sarson是您应该考虑的两个标准。如果您的团队/公司已经使用了一个，请使用它！如果没有，请选择一个。不要重新发明轮子，并帮助您的读者已经熟悉这些符号立即理解您的图表。

许多人经历了在2019年的Big AWS图标改造过程中如何增加认知负荷。

亚马逊网络服务确实完全大修他们的AWS架构图标。人们需要几个月的时间来切换到使用它们。我们仍然看到今天新图中使用的旧版。我们已经习惯了这些旧图标，即在开始时，了解与新的图表所需的认知负载显着更高。我们必须重新学习习语并重新训练我们的大脑以记住这些块。与此同时，我们必须仔细阅读图标的小细节。就像你需要仔细阅读外语阅读单词的字母。

关键思想：最大限度地减少认知负荷，重复使用模式，习语，观众已经熟悉的图标。

在绘制图表时，您通常会旨在添加一些较低级别的细节。因为这种特定的东西很重要。请不要。

一个广泛的错误是在图中混合抽象级别。这真的增加了认知负荷。

如果您需要在较低级别记录某些内容 - 我们通常会进行 - 创建另一个图表。

C4模型更精美地描述了这种精美，并以特定的抽象级别为中心。即使您不想遵循此框架，请查看它，因为它清楚地描述了这一点。

当您希望将较低级别的项目添加到更高级别的图表时尤其如此。

但是相反仍然有用。例如，如果您使用详细信息描述某些系统，并且您需要记录与卫星系统的一些有用但不太关键的交互，您可能会选择删除此不那么关键的作品，或者以更高的方式记录它 - 卫星系统的“盒子”。这样，记录了依赖关系或互动。在这种情况下，它有助于将重量保持在认知负载上合理的。它可以节省有关该卫星系统的许多细节，这些系统不是图表的焦点。

关键想法：不要无理由混合抽象级别。避免将较低级别的信息添加到图中。

创建好的图表需要时间和精力。以及他们记录的系统进化。他们通常很快进化。您和您的读者，不希望该图已过时。通常，较高级别的图表，变化较慢。从这些开始！特别是因为它们提供了有用的背景，以在您和读者之间建立这种共同点。无论如何，较低级别的图表将是必需的。

关键主意：以较高的级别图表开始。他们迅速发展，建立共同点非常有用。

在我们与自我评估原则和清单结束之前，让我们回顾一些真实例子所涵盖的内容。

第一个示例来自Magento的官方文档：下图说明了组件并显示了Magento中的“图层”或层。

在加方面，它们包括一个描述每个颜色手段的传奇。至少，一些颜色。读者留下了想知道为什么众多箭头中的一些是蓝色的，而其他箭头则是红色的。这是否意味着协议上的任何内容？在身份验证方案上？在API版本？这是不可能的。左上角的集成盒比知识曲线提出更多问题。如果它没有与系统的其余部分互动，它是如何运行的？为什么需要在图表中？当我读到这一点时，我真的有这么多的问题，它并没有帮助我弄清楚玛托如何工作。

下一个例子来自ConceptDraw示例库。我对来自自称为“世界级的业务示意图，思想管理和项目管理平台”的展示的期望。

这里有好事：我们有更多的标签。他们使用标准图标（较旧的AWS图标）。但为什么他们中途停止？我的假设是它是一般的例子，所以它没有描述一个真实的系统，所以很多细节都是未知的。我们看到很多数据库。你还记得什么时候，我们说点之间的连接比点更重要：在这种情况下，如果他们在连接上放置标签来解释每个数据库的目的，它会帮助很多，因此回答隐含问题“为什么这么多不同的？”最明显的标签是在右上方的3个实例中分组。读者的出卖将是：一些东西在向代理发送东西之前移动并处理。这有助于理解系统吗？

目标不是指向手指。它显示了制作图表是多么容易，如果作者花了一些额外的时间来查看预期的受众读取它们并验证它们可以使用该图以了解所描述的系统如何工作的方式，这可能是非常有帮助的。建筑玛格托的人很聪明。如果聪明人在他们的文档中创建平均看图，我们中的许多人都很有可能不会更好。这就是为什么我相信使用清单，指导方针和一些原则来帮助我们。这就像一个食谱。一开始，你依赖它。当您多次生成良好的结果时，您将其内化，与规则一起播放，并仅使用时间检查。在某些时候，您不再需要指导方针，但它们有助于达到这一点。

读者应该找到答案和新知识。如果读者向我们询问关于该图的问题（不是关于系统），那是一个标志：我们有改进的空间，使其更容易理解！

事情会很快改变。我们从未有足够的时间/精力保持最新状态，因此我们应该根据满足第1条规则尽可能地建立尽可能少的维护工作。

与许多文档一样，您需要外部反馈以优化您的图表，找到缺陷，识别尚不清楚的部件。在我的经验中，我们投资时间很少审查图表改善它们。我们大部分时间只创建或消耗它们。

代码审查或设计评审已从同行中教授此反馈的价值。我们应该是勤奋，并在我们认为他们完成之前审查了我们的图表。

每个形状应该映射到一个概念。每个概念都应该映射到一个形状。

那说，我有我最喜欢的。这里没有银耳子弹，我更喜欢哪种工具取决于图表的类型，它的生命周期（这是一个用于小知识渊博的观众的短暂生活，或者是一个需要更多护理的长寿）

作为经验的规则，我尝试仅使用一个工具，它很容易将源存储在git中，如果需要，在某些渲染之上。

美人鱼对于序列图，简单的流程图或状态图表或实体关系图非常棒。 直接在Vscode，Gitlab或Mkdoc中支持，它在工具箱中真的有些东西。 www.diagrams.net/（fka draw.io）源不是友好（但仍然让我们轻松存放在git中），但它一旦需要在造型，布局中投入更多时间就是一个非常好的工具 ，即当该图变得更大，当您需要更抛光的东西时。 GraphViz值得一提到，因为它占据了一个特殊的地方。 首先，它是完美的版本控制。 然后，我通常在草稿阶段使用它。 最后的渲染通常不是很抛光（除非你投资很多努力），但它有助于尝试，探索和寻找一些布局。 它并不总是有用的，但你不应该忽略它！ 此清单受到大C4清单的严重启发，其中一些项目删除或合并，其他一些物品 ......