为什么图表对您的开源项目文档至关重要

如果您曾经访问过 GitHub 上的一个项目（例如），目的是了解它如何融入更大的系统，您会认出当您在初始登录页面上（或很容易从那里找到）找到一两个图表时，您所体验到的如释重负的感觉。 这是一篇关于架构的重要性，尤其是图表的重要性的文章。

我是一位坚定的开源倡导者，但是源代码不足以使一个项目成功，甚至，我想补充说，不足以成为一个真正的开源项目：您的文档不仅应该对每个人都可用，而且应该对每个人都可访问。 如果您想让人们参与进来，提供一种参与方式至关重要。

除此之外，我认为我们在开源方面有责任（并且有机会！）促进多样性。 提供图表有助于解决（至少！）四种类型的多样性：

• 母语与您的主要文档的语言不同的人
• 阅读大量文本有困难的人（例如，患有阅读障碍症的人）
• 比文本更倾向于视觉思考的人（像我一样！）
• 希望从不同角度（例如，安全性、管理、法律）了解您的项目的人

这篇文章的出现是因为我最近参加了一个虚拟演示。 该演示没有成功，但是我们没有人感到压力：这是一个内部演示，而且这些事情经常发生。 这是我们都熟悉的地方，当团队的一位成员在幻灯片演示进行到几页时，屏幕上弹出一个消息，说“演示 NO GO!” 时，我们都为该项目的团队负责人（正在进行演示）感到难过。

道歉之后，她问我们是想完全放弃还是只是讨论他们手头的信息。 我们选择了后者——毕竟，大多数不强调用户体验组件的演示，除了终端窗口之外，也展示不了多少东西，至少我们大多数人可以在半小时左右的时间内伪造出来。

幸运的是，演示团队的成员有很多关于它将向我们展示什么的信息，并且有一个特别好的架构图可供讨论，因此尽管演示存在问题，我们还是进行了一个富有成效的会议。 她回答了几个问题，然后我插话问了一个关于安全性的问题。

本文本可以关于一个早期演示中展示的项目的安全性故障：这是安全性在流程中被推迟到后期（通常为时已晚）的另一个示例，那时集成既困难又昂贵。 但是，很明显，该团队已经考虑了安全性的特定方面，包括网络上的安全性（传输中）和存储中的安全性（静态）。 尽管可能还有改进的空间（什么时候没有呢？），但一位团队成员在通话过程中向我发送了更多文档，使我能够理解该团队所做的一些选择。

本文是关于我们可以进行讨论的事实。 幻灯片演示文稿包含一个架构图，其中显示了所有主要组件，箭头显示了数据流的方向。 它是清晰的，并使用颜色编码来显示不同组件的来源 - 哪些组件来自外部项目，哪些来自内部项目，哪些是此演示的新组件。 参与通话的人员（全部是技术人员）能够一目了然地了解正在发生的事情，并且提供描述的团队负责人对各种流程有清晰的解释。 她的团队成员纷纷加入，以回答具体问题或提供有关特定点的更多详细信息。 这就是技术讨论应该进行的方式，并且有一件事特别令我高兴（除了该项目考虑了所有安全性！）：有一个架构图可供讨论。

世界上没有足够的安全专家可以四处走动，这意味着并非每个项目都有机会让安全社区的成员详细审查其设计的每个阶段。 但是，在分享的时候，图表是无价的。 我很讨厌想起有多少次我被要求查看一个项目，并给出我对它的安全性方面的想法，但发现唯一可用的只是代码和组件文档的混合，而没有解释所有这些如何组合在一起，更糟糕的是，没有架构图。

在构建项目时，您和您的团队通常非常投入到细节中，以至于您知道所有内容如何组合在一起，并且可以将它放在您的脑海中或向同事描述关键点。 当有人需要提出不同类型的问题或从不同的角度审查架构和设计时，问题就来了。 图片——架构图——是向外部各方（或项目的新成员）宣传技术层面上正在发生的事情的绝佳方式。 它还具有许多额外的好处：

• 它迫使您考虑是否可以以这种方式描述所有内容。
• 它迫使您考虑抽象级别以及应该在什么级别显示什么。
• 它可以揭示以前不清楚的关于依赖关系的假设。
• 显示各种组件之间的数据流很有帮助。
• 它允许与母语不是您的主要文档语言的人进行更简单的对话。

需要明确的是，这不仅仅是一个安全问题——其他非功能性需求（如高可用性、数据一致性、性能或弹性）也是如此——但我是一名安全人员，这就是我遇到这个问题的方式。 我也意识到我有一个非常视觉化的头脑，这就是我喜欢了解新事物的方式。 但是，即使对于那些不倾向于视觉化的人来说，图表至少提供了一个机会来确定自己的方向，并弄清楚您需要在哪里更深入地研究代码或执行。 我也相信，对于任何具有重大复杂性的系统，任何人都几乎不可能考虑所有的安全隐患（或任何更高阶的涌现特性和质量），而没有架构图。 这包括设计系统的人员，因为没有系统是单独存在的（或者它毫无意义），因此您无法在任何时间内将所有这些部分都放在您的脑海中。

我之前写过关于构建演化架构这本书，它在帮助项目考虑管理可以变形或改变优先级的需求方面做得非常出色。 毫不奇怪，这本书大量使用了架构图。 Enarx，一个我密切参与的项目，一直有很多图表，所以我知道这里涉及到一些开销，包括在设计更改时更新图表，以及考虑为我们的文档的不同消费者提供哪些抽象，但我真的相信这是值得的。 每当我们向项目介绍新人或进行演示时，我们都会确保至少包含一个图表（通常更多），当我们在演示结束时收到问题时，它们几乎总是以诸如“请回到幻灯片x上的图表”之类的短语开头。

我强烈建议您创建图表，这既是为了您自己的利益，也是为了将来会查看您的项目的任何人。 它是成为一个开放项目的关键部分——架构的开放意味着代码，从而项目本身，变得更容易访问，并且对更广泛的社区更加开放。 社区成员会欣赏它（您也应该如此）。 您的图表不必完美。 但它们确实需要存在。