软件架构文档：综合指南

软件开发团队为软件架构做出选择背后的原因常常被迷失。新团队成员常常对为什么开发人员选择 Ruby 或 React 这样的编程语言，或者为什么他们在一个平台而不是另一个平台上托管软件感到困惑。

出于这个目的以及更多目的，负责软件架构开发的团队可能希望记录他们的决策。尽管开发人员、软件架构师和其他感兴趣的各方经常对软件架构中文档的价值持怀疑态度，尤其是在他们认为代码文档本身的敏捷环境中，但良好的文档对于正常运作的团队来说绝对是必不可少的。

正如我们将看到的，软件架构文档对于开发团队尤其重要，因为代码根本无法讲述整个故事。许多问题仍未得到解答。局外人查看代码无法判断为什么架构以某种方式构建，或者进行更改是否会对系统的完整性产生负面影响，从而严重阻碍更改。

目录

什么是软件架构文档？

为什么我们应该记录软件架构？

如何创建软件架构文档

软件架构文档的最佳实践

软件架构中的文档技术

软件架构文档模板

用于软件架构文档的 Baklib

什么是软件架构文档？

软件架构文档是软件系统架构的完整文档，包括深思熟虑的设计决策、组件和一些特定的工件，例如图表、规格和描述。它告诉您代码是如何以及为何如此构建的，并使团队成员和客户能够理解和改进软件。

软件架构文档旨在记录代码的以下区域：

系统的非功能性需求

系统的目标

驱动架构的决策及其背后的推理

因此，虽然好的代码自然会说明一切，但软件架构的某些方面是不言自明的，这就是好的文档的用武之地。它使软件的未来维护和更新成为一个更加可行的过程。

软件架构文档通常针对这些感兴趣的各方：

开发商

软件架构师

测试人员

质量保证

支持

客户

行动

项目经理

以及与软件解决方案的架构方式有利害关系的任何其他人。如果您没有记录软件架构，那么您将面临无法了解其构建原因和方式的风险，在进行更改时可能会逆转和破坏之前的选择。

为什么我们应该记录软件架构？

我们刚刚谈到了为什么软件开发团队可能想要记录他们的软件架构，现在我们将更深入地探讨这样做的原因。

知识共享

虽然文档在许多技术贡献者的任务列表中通常排在后面，但它对于软件架构领域的知识共享至关重要。随着时间的推移，团队成员可能会忘记为什么做出决策，并冒着以不符合最初使命的方式更改软件的风险。记录软件架构意味着开发团队可以更好地共享知识并为未来的贡献者保留这些知识，这些贡献者可能与原始创建者完全不同。

合作

正确的软件架构文档使团队能够更有效地协作，因为所有利益相关者都可以理解系统。代码背后并非立即显而易见的意图变得更加清晰，甚至技术水平较低的用户也可以理解代码如何以及为何以这种方式运行，从而实现更好、更实际的业务决策。

可扩展性

为了扩展项目，您需要记录架构、规范和其他技术细节背后的设计决策。如果没有正确记录，您的团队和架构就无法成长，因为重要信息将会丢失，并且您的软件可能注定会失败。第一次使用软件时，您的范围可能会受到限制，但随着您接受更多功能和用例，这种情况可能会随着时间的推移而改变。

降低维护成本

如果您的软件要开发并跟上客户需求，您的开发人员将需要对代码进行定期维护，以确保修复错误等。如果您的软件架构已正确记录，这意味着任何开发人员（甚至是新开发人员）理论上都可以加入并自信地进行更改。这降低了代码的维护成本，因为更新和修补更加容易。

维护和现代化过时的软件

随着软件的发展，它还必须满足不同的且日益严格的要求，但利益相关者经常会由于变化的步伐而失去对软件的跟踪。软件必须得到维护，更重要的是，必须进行现代化，这需要更新的软件架构。可靠的文档会告诉您需要进行哪些更改以及哪些地方可能无法满足标准。

决策支持

正确的文档可以支持架构师、开发人员、项目经理和其他负责推动访问更多信息的各方的决策。尽管有些人认为简单地查看代码就可以提供所有必要的洞察力，但现实是这种方法完全缺乏意图和上下文。软件架构文档填补了这一空白。

另请阅读：什么是软件文档？它的类型和最佳实践

如何创建软件架构文档

现在，我们将介绍创建软件架构文档时需要采取的步骤。

了解受众和目的

与所有形式的写作一样，您需要了解软件架构文档的目标受众。您最初可能会想到其他软件架构师，但受众也可能包括开发人员、技术作家、项目经理和客户。通常明智的做法是针对不同的受众制定不同的文档，因为可能与某些受众相关的信息可能会分散其他受众的注意力或使其不知所措。

收集现有信息

您想要为软件架构创建的文档可能已经以某种形式存在。如果您收集现有材料，这将节省您在文档过程中的时间，并确保您充分利用您的资源。采用这种方法可以使您的所有抵押品更有可能是最新且准确的，并将所有重要信息保存在一个地方。

选择文档格式

您需要决定是否要将文档呈现为图像、文本、视频或上述的某种组合。不同的格式需要不同的资源，并且随着时间的推移，更新或翻译成多语言内容会变得更加困难。考虑哪种格式最适合您的用户并且具有最低的维护成本，以确保对文档的持续承诺。

概述文档

在开始创建大量软件架构文档之前，请确保首先构建一个大纲，以便您了解它们是如何组合在一起的。您可能会有许多协作者参与您的文档工作，因此每个人都需要有一个可以使用的路线图，就像他们使用软件代码一样。

变更管理和版本控制

您的软件架构文档会随着时间的推移而变化，因此您需要有一个正式的变更管理系统以及版本控制规定。版本应在保持原始版本完整的情况下进行更新，以防出现争议或需要撤销，并让团队中的每个人随时了解文档的最新版本。

包括附录和参考文献

在创建软件架构文档的过程中，您可能会参考外部资源和材料。确保包含附录和参考文献，以便文档用户可以查找原始来源并找到更多信息，确保您的文档全面且可靠。

定期维护和更新

软件架构文档的最终产品永远不会完成，必须随着系统的改进、更改和更新而进行调整。高质量的文档准确地反映了系统的细节，让用户相信它确实有用。这需要随着软件架构的发展定期维护和更新文档，同时保留原始版本以供参考。

软件架构文档的最佳实践

现在考虑这些用于实现软件架构文档的最佳实践。

1. 在开发阶段实施文档

如果您有时间，完整的文档应该被视为原型的一部分，而不是事后的想法。文档应该与代码一样重要，因为它为开发软件的关键利益相关者提供了见解和信息。重要文档应与代码一起生成，以跟上不断发展的产品的步伐。

2. 仅记录您需要的内容并保持最新

完整的文档并不意味着您记录所有内容 - 您应该只记录您需要的内容，否则可能会导致用户感到不知所措并疏远他们，因为他们认为文档过于强大。简洁、相关且最新的文档比大量冗长的文档更能满足用户的需求。这里的目标是提供足够的文档，而不是太多。

3. 不同利益相关者的文件

正如我们已经讨论过的，您将需要针对不同利益相关者的不同形式的文档。软件开发团队中有许多角色可能对软件架构文档感兴趣，如下所示：

开发商

当然，开发人员会对软件系统的细节感兴趣，包括规范、依赖关系和组件关系。为了最有效地开发代码，开发人员必须了解软件架构，从而使他们能够避免破坏事物或进行次优更改。

测试人员

测试人员负责有意识地尝试破坏软件以检查弱点，因此，他们必须对其架构和设计决策有深入的了解，以便他们可以创建有效的测试用例。

项目经理

项目经理必须对软件架构有一个广泛的概述，以帮助他们了解什么是可能的并推动项目向前发展。分配资源需要了解软件的限制以及在合理的时间内完成某些里程碑所需的技能。

技术作家

技术作家绝对必须了解系统架构才能为用户创建有效且有用的文档。所有文档都是相互关联的，需要告知不同类型文档的作者。对文档感兴趣的软件架构师也可能受益于专业技术作家的帮助。

4.避免歧义并保持简洁

当您的利益相关者正在寻找有关软件架构的文档时，他们需要您避免歧义并保持简洁。如果您引用特定组件，请确保与您的命名约定和术语保持一致。

5. 精细的可访问性

精细的可访问性对于在文档门户中搜索特定信息的用户非常重要，因此您需要结合搜索内容的功能，并对某些用户和内容的访问权限进行限制。保持结果的相关性和有用性是文档被采用的关键。

软件架构中的文档技术

现在我们将看看软件架构文档中的这些常见技术。

图表

有时，没有比通过可视化图表（通常使用统一建模语言（UML））更好的方式来表达软件架构了。如果您想向用户解释系统的设计，包括系统各部分如何协同工作，以及信息如何在系统的不同部分之间流动，那么图表是一个有用的工具。

文本文档

另一方面，文本有时是理解更复杂的观点的唯一方法，这在记录软件架构时尤其重要。使用文本文档可以帮助您解释高级概念、详细说明组件的功能等等。

混合文档

当然，使用图表和文本的组合通常是向不同的用户群展示文档的最佳解决方案。图表可以任意复制，并附有文字来解释您的意思。

软件架构文档模板

这是一个根据 arc42 的通用软件架构文档模板。它是开源的并且完全免费使用，消除了构建软件架构文档的痛苦。

用于软件架构文档的 Baklib

Baklib 是一个卓越的平台，旨在简化和提升创建和管理软件架构文档的流程。在软件开发领域，清晰而全面的文档是成功的项目执行、协作和知识保留的关键组成部分。 Baklib 提供了专为软件架构师、开发人员和技术作家量身定制的用户友好且功能强大的解决方案，使他们能够轻松高效地创建、维护和共享软件架构文档。

总结

最终，开发、更新、维护软件以及添加新功能的人可能不是最初构建该软件的人。出于这个原因，以及前面提到的其他原因，记录您的软件架构以确保您的软件继续有效运行是一个非常好的主意。如果没有适当的文档，软件团队可能会陷入混乱并迷失方向。当工程师离开他们的职位并且他们的继任者不知道为什么做出某些决定时，软件架构变得难以理解。

虽然文档可能并不总是软件架构师的首要任务，但您的团队成员和用户将感谢您所做的努力。