如何编写软件架构文档

排版 / 以码为梯

文章字数 / 1996

如何成为架构师系列文章（译文）的第五篇，欢迎转发、评论、收藏

在确认了软件架构中的利益相关者，功能性和系统架构中的非功能性需求有哪些后，我们需要将这些内容用文档记录下来。这也是为什么我们要在这篇文章中讨论软件架构中的文档的原因。

在深入讨论之前，我首先要说明我们认为的架构文档是什么样的。不幸的是，编写架构文档没有可以遵循的标准。而且，每个公司都有自己的一套关于文档编写的规范。

在这篇文章中，架构文档指的是系统的顶层描述，展示整个架构工作的基本原理。架构文档的主要目的是关联功能性和非功能性需求。

我们为什么需要架构文档？

在描述如何编写架构文档之前，我们需要理解为什么需要这些文档。架构文档的三个主要目的如下：

对于任何文档，无论是项目文档，开发文档还是架构文档，最值得关注的问题是，创建并维护文档是否值得。对于这个问题可以通过下面的简单公式来表示：

(Cx — Cy) > Cdiff

Cx代表没有文档时项目所需要的成本

Cy表示项目有文档时的成本

Cdiff表示管理文档的成本

使用以上的公式可以很容易回答是否该创建文档，创建什么类型的文档，以什么样的频率更新文档等等类似的问题。这也可以回答对于小的项目，短期考虑或长期考虑情况下是否需要文档这样的问题。

但是，一个没有文档的项目怎么会比一个有文档的项目成本更高呢？想象一下你有一个200人的团队，持续五年，每个开发者在一个项目上的时长为两年。如果没有文档，即使是做很小的改动也是非常混乱的。下面会给出如何维护文档的一些小建议。

图表的类型

让我们考虑一下可以在文档中使用的架构方案和图表类型：

这是最常见的一种图表类型，可以以任何形式展示。通常是用于利益相关者之间交流的最方便快捷的方式。这种非正式的图表的缺点是，不同理解程度的人，看到的图都是一样的，所以需要添加很详细的说明。

Informal diagram example

它是具有一定创建规则的标准图形方案或图表。它的缺点是对于每个元素没

有提供完整的描述。因此，想看懂这种图需要特定图表的语义知识。此外，还需要额外的软件来完成图表的创建，UML就是属于这种类型的图表。

Semiformal diagram example (C4 deployment diagram example ）

它在某种形式上是一种描述架构的语言，允许直接从创建的架构方案生成代码，它更适用于硬件系统工程。缺点之一是：它需要特殊的软件和知识，用于编写和理解。

编写架构文档的一些建议

在工作中，我经常会写文档并维护它。接下来我分享一些编写架构文档的基本原则：

DRY（Don’t Repeat Yourself）原则无论是在编码还是在编写文档中都适用，在编写文档时，遇到重复的内容，使用链接来避免重复内容。

这有可能是重要的原则。给开发人员编写的文档跟给高级管理者的文档肯定是不一样的。因此在编写文档时需要弄清楚文档为谁而写，然后了解这些人在你的文档中需要看到什么以及他们试图找到什么答案。

这是文档编写中经常遇到的问题。比如，你提出一个问题的解决方案并以图表的方式记录了它。你理解它，知晓它的上下文，但是看文档的人可能不清楚上下文，那么这种情况下对你来说一清二楚的内容却会对他们造成混乱。因此，在写文档时你应该提供图表的上下文作为描述。

此外，还可以尝试一些标准化方法。例如，我非常喜欢使用C4标准来描述我的解决方案，因为这种方式允许你先在顶层对系统进行描述，然后深入到组件、容器和部署的细节，并且对于每个元素的描述都有合理正式的标准。

跟代码一样，文档也需要定期评审。在评审的过程中，很可能会找到已失去相关性且值得更新的地方。另外，尽量将文档分享给软件架构中的利益相关者并寻求他们的观点，这在刚刚开始编写架构文档时尤其有用。

画图常用的工具

工欲善其事必先利其器，想编写好的架构文档，一些画图工具肯定是少不了的，接下来我就分享一些常用的画图工具给大家：

你可以使用它绘制任何的图，它的缺点是不能在Mac上运行，而且还是收费的。

这个软件是为Mac用户提供的，但是是收费的。

这是一个收费软件，但是有30天的免费试用。

我最喜欢的一个在线绘图工具。它支持从C4到AWS规范的第三方插件。你可以在任何平台上做任何你想做的事，非常适合作为创建非正式图表的白板工具。最关键的是，它是免费的。

这也是一个在线的绘图 站。

大家对于编写架构设计文档有什么好的想法或者有一些好用的画图工具欢迎评论交流。