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

如果你曾经访问过 GitHub 上的一个项目（例如），目的是了解它如何融入更大的系统，你就会体会到在初始登录页面上（或容易访问的地方）找到一两个图表时的解脱感。 这篇文章是关于架构的重要性，特别是关于图表的重要性。

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

除此之外，我认为我们在开源中对多样性负有责任（和机会！）。 提供图表有助于解决（至少！）四种类型的多样性

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

这篇文章是在我最近参加一次虚拟演示后产生的。 演示没有成功，但我们没有人感到压力：这是一个内部演示，这种情况很常见。 我们都熟悉这个环境，当几张幻灯片之后，她的团队成员之一在她屏幕上弹出一个消息说“演示失败！”时，我们都为项目负责人（正在做演示）感到惋惜。

在道歉之后，她问我们是否想完全放弃，或者只是讨论他们手头的信息。 我们选择了后者——毕竟，大多数不关注用户体验组件的演示，至少不会比我们大多数人能在半小时左右伪造的东西展示更多终端窗口。

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

这篇文章本可以写一个早期演示中出现安全漏洞的项目：这是安全被推迟到过程后期（通常太晚）的另一个例子，此时集成既困难又昂贵。 然而，很明显，该团队已经考虑了网络的特定安全方面（传输中）和存储（静态）的安全方面。 虽然可能还有改进的空间（什么时候没有呢？），但在通话过程中，一位团队成员向我发送了更多文档，让我能够了解该团队所做的一些选择。

这篇文章 *实际* 要讲的是我们能够进行讨论的事实。 幻灯片中包含一个架构图，显示了所有主要组件，并用箭头显示了数据流的方向。 它清晰且颜色编码，以显示不同组件的来源——哪些组件来自外部项目，哪些来自内部项目，哪些是这个演示的新组件。 通话中的人（都是技术人员）能够一目了然地看到发生了什么，而提供描述的团队负责人对各种流程都有清晰的解释。 她的团队成员参与进来回答具体问题或提供有关特定点的更多细节。 这就是技术讨论应该进行的方式，特别让我高兴的一件事是（除了项目考虑过安全之外！）：有一个架构图可以讨论。

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

当你在构建一个项目时，你和你的团队通常非常专注于细节，以至于你 *知道* 它是如何组合在一起的，并且可以将其保存在你的脑海中，或者向同事描述关键点。 当有人需要提出不同类型的问题或从不同的角度审查架构和设计时，问题就来了。 图片（架构图）是让外部人员（或项目的新成员）了解技术层面正在发生的事情的好方法。 它还具有许多额外的好处

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

需要明确的是，这不仅仅是一个安全问题——对于其他非功能性需求（如高可用性、数据一致性、性能或弹性）也是如此——但我是一名安全人员，这就是我体验这个问题的方式。 我也知道我有一个非常视觉化的头脑，这就是我喜欢了解新事物的方式。 但即使对于那些不擅长视觉的人来说，图表至少提供了一个让你定位自己并找出需要在哪里深入研究代码或执行的机会。 我也相信，如果没有架构图，任何人都不可能考虑任何具有重要复杂性的系统的所有安全隐患（或任何高阶涌现的特征和质量）。 这也包括设计系统的人，因为没有系统是独立存在的（或者没有意义），所以你不可能长时间将 *所有* 这些片段都保存在你的脑海中。

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

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