软件架构文档创造了共同的理解（在同一种语境上下文BC中的达成共识）
软件架构文档至少应该支持开发团队，例如，当一个新的团队成员新入职，会有很多问题：
- 在哪里可以找到系统构建块的概述？
- 你为什么使用Angular而不是React？你为什么使用Hibernate而不是jOOQ？
- 系统部署在哪里以及如何部署？
- 有什么我需要注意的约定吗？
这将我们带到了软件架构文档的第一个目标：
软件架构文档为各种利益相关者创建了对系统背后的解决方案的共同理解
通常有许多不同的利益相关者对我们系统的不同方面感兴趣：软件架构师、软件工程师、Ops、支持、测试、PO、项目经理、SME、业务赞助商等。
通过形成对系统软件体系结构的共同理解，您可以创建系统体系结构的不同视图。
有了这种理解，各种利益相关者就可以从他们的角度评估底层软件架构。
这样，我们就可以通过评估部分具体化上述目标：
文档使从不同利益相关者的角度评估软件架构成为可能
软件架构文档允许您的利益相关者判断系统是否实现了目标，因为他们通常无法深入研究代码。
有了好的架构文档，他们可以回答以下问题：
- 所选架构是否适合解决方案？
- 架构是否合适？
通过这种方式，架构文档通常可以防止其他目标、约束和非功能性需求的出现。
我经常听到各种利益相关者说：“系统必须很快。”
但是，这是什么意思？
作为软件架构师，您必须将这些期望转化为具体的质量目标，即具有支持质量场景的非功能性需求。您将这些质量目标记录在架构文档中，这反过来会帮助您的团队根据商定的非功能性需求实施解决方案。
软件架构文档支持架构工作
软件架构是一项团队工作，因此软件架构文档支持您的团队工作是最重要的。
作为团队成员，重要的是主动了解（并传递给新的团队成员）团队内的目标、约束和非功能性需求。此信息在团队架构研讨会中通常非常重要。
做出易于理解和理解的架构决策非常重要。没有什么比不知道自己为什么做出这样的决定更让人恼火的了。
软件架构文档指导开发团队实现新产品功能
记录软件架构有助于整个开发团队实施解决方案。
- 我需要考虑哪些限制？
- 我需要测试哪些非功能性需求？
- 我需要遵循哪些总体概念？
- 在实现特定功能时是否需要考虑架构决策？
软件架构文档支持与外部利益相关者的沟通
软件架构工作的很大一部分是通信。特别是，与利益相关者的沟通是有效和有针对性的讨论结果的关键。
良好的软件架构文档支持与外部利益相关者的沟通。它包含软件架构的不同的和涉众适当的视图。
我们应该如何构建软件架构文档？
一种经过验证的构建软件体系结构文档的方法是arc42 模板。
什么是arc42模板？
- arc42提供了一个用于记录和交流软件
- 和系统架构的模板。
- arc42基于各个领域的许多系统的实践经验，
- 从信息和网络系统、实时和嵌入式到商业
- 智能和数据仓库。
- arc42支持任意技术和工具。
- arc42完全独立于流程，特别适合精益和敏捷开发方法。
- arc42是开源的，可以在商业和私营部门免费使用。
- arc42有多种语言版本。
- arc42有不同的格式，例如 .adoc、.docx、.rst、.md、.tex、...
arc42 文档的好例子
- HTML 完整性检查器 (HtmlSC) 架构文档(Gernot Starke)HTML 完整性检查器 (HtmlSC) 应支持作者创建带有超链接的数字格式以及图像和类似资源的集成。
- DokChess (Stefan Zörner) DokChess 是一个功能齐全的国际象棋引擎。
- Gradle 作为 arc42 的示例(Stefan Zörner) Gradle 自动化软件的构建、测试和交付。
使用 arc42 处理时是否存在任何可能的陷阱？
- 不要提前记录所有内容。将 arc42 模板视为文档柜。你在工作时把东西放在架子上。这就是软件架构文档出现、发展和保持最新的方式。
- arc42中最重要的是结构。该结构不为指南或问答部分提供空间。
- 不要在软件架构文档中写客户特定的东西，除非你的构建块是以面向客户的方式构建的。
替代文档和结构化方法
有一些替代的结构化和文档化方法。
我们应该如何可视化软件架构？
C4 模型是获得通用抽象集的好方法。这是一种抽象优先的方法，并且与符号无关。
C4 模型从容器、组件和代码的角度来看待软件系统的静态结构。人们使用我们构建的软件系统。
1、C4中的软件系统是什么？
软件系统是最高级别的抽象，它描述了为其用户增加价值的东西，无论他们是不是人类。
2、C4中的容器是什么？
容器（不是 Docker！）是一个可单独部署/可执行的东西。
3、C4中的组件是什么？
组件是封装在定义良好的接口后面的一组相关功能。如果您使用的是 Java 或 C# 之类的语言，那么最简单的方式就是将组件视为接口后面的实现类的集合。
C4的核心观点是什么？
通过抽象，我们可以创建上下文视图（级别 1）、容器视图（级别 2）、组件视图（级别 3）和代码视图（级别 4）。
C4模型兼容arc42吗？
是的，arc42和C4可以互补使用。
C4 图与以下 arc42 章节相关：
- C4 System Context图可以放在arc42第3章“Context and Scope”
- C4 Container Diagram可以放在arc42第5章Building Block View (Level 1)
- C4组件图可放在arc42第5章积木视图(Level 2)
- Code Diagram可以放在arc42 Chapter 5 Building Block View (Level 3)
除了上面介绍的 C4 图，还有一些额外的 C4 图可以插入到 arc42 中。
我们如何编写和管理软件架构文档？
与任何软件一样，对技术文档也有要求。Gernot Starke 在以下博客文章中出色地记录了这些要求：
https://www.innoq.com/en/articles/2022/01/principles-of-technical-documentation/
什么是“文档即代码”？
“文档即代码”意味着您的文档过程受益于您用于开发成功软件的相同实践。
其中一些做法是：
- 在版本控制系统中存储内容
- 内容、配置和表示分离
- 使用自动化进行编译、验证、验证和发布 (CI/CD)
- 重复使用共享材料 (DRY)
- ...并使用您的 IDE 编写内容 ;-)
通过这种技术，我们获得了一些开箱即用的价值：
- 将整个文档结构化为子文档
- 根据特定的利益相关者重组文档
- 参考图像，不嵌入
- 简单的版本控制“将文档作为代码处理”
- 源代码等文档内容的格式
- 文档审查、拉取请求、通过 Git 工具进行版本控制
- 转换为各种演示格式，如 HTML5、PDF、DocBook、Confluence 等
是否有任何推荐的文档即代码工具？
在文档即代码中，我们可以区分以下过程步骤：创作（编写、验证和预览文档内容）、转换（文档为 HTML、DocBook、PDF 等发布格式）和发布（构建和部署文档工件). 对于这些步骤中的每一个，我都可以推荐一些工具来完成流程步骤。
创作：AsciiDoc
AsciiDoc是一种用于编写技术内容的纯文本标记语言。使用AsciiDoc格式编写您的内容。
转换：Asciidoctor
Asciidoctor是一个快速处理器，用于将 AsciiDoc 解析为文档模型并将其转换为输出格式，例如 HTML 5、DocBook 5、手册页、PDF、EPUB 3 和其他格式。
发布： Maven、Gradle、docToolChain
docToolchain是一组脚本，可以轻松创建和维护强大的技术文档。基于同类最佳的开源技术，我们提供了最好的文档工具链，因此您不必这样做。
什么是图表？
与文档一样，您可以像对待代码一样对待图表。
1、作为代码 1.0 的图表
在文本中描述图表的经典方法可以使用PlantUML、Mermaid或GraphViz来完成。
2、图表即代码 2.0
如果我们可以用文本形式描述我们的 C4 模型并直接生成 C4 图呢？这就是Structurizr的用武之地。它将图表作为代码带入了一个新的维度——图表作为代码 2.0。
使用Structurizr DSL，我们可以用 C4 抽象来描述软件。
在描述了我们软件系统的 C4 模型之后，我们可以直接创建所有定义的视图（具有不同的表示）。
将一切结合在一起
现在您拥有了软件架构文档的整个工具箱：
- 用arc42构造它
- 使用C4 模型对其进行描述和可视化
- 使用AsciiDoc、AsciiDoctor、docToolChain和Structurizr像对待代码一样对待您的文档和图表
- ...并将其集成到您的开发工作流程中。
我创建了一个示例存储库，将所有这些技巧和技术结合在一起。
进一步支持软件架构文档工具