18 软件架构文档化

18 软件架构文档化

如果不写下来，它就不存在。
—Philippe Kruchten 菲利普 克鲁奇顿

如果需要使用它的人不知道它是什么，那么即使是最好的、最适合这项工作的架构，在本质上也是无用的；无法很好地理解它，无法使用、构建或修改它；或者（最糟糕的是）误解并错误地应用它。架构团队的所有努力、分析、辛勤工作和富有洞察力的设计都将白费。他们还不如去度假，因为他们的架构会带来很多好处。

仅仅创建一个架构是不够的。它必须以一种方式进行沟通，让其利益相关者正确地使用它来完成他们的工作。如果你费心创建一个强大的架构，一个你希望经得起时间考验的架构，那么你必须费心足够详细地描述它，没有歧义，并组织它，以便其他人能够快速找到和更新所需的信息。

文档为架构师说话。今天它为架构师说话，架构师除了回答一大堆关于架构的问题外，还应该做其他事情。明天，当架构师离开这个项目，而现在有新人来负责它的发展和维护时，它还能为架构师说话。

可悲的事实是，今天的架构文档，如果真的完成了的话，往往被视为事后诸葛亮，这是人们不得不做的事情。也许合同需要它。也许是顾客要求的。也许公司的标准流程需要它。事实上，这些可能都是合理的理由。但它们都不足以产生高质量的文档。为什么架构师要花费宝贵的时间和精力，让管理者检查可交付成果/p>

最好的架构师制作好的文档并不是因为它是“必需的”，而是因为他们看到它对手头的事情至关重要，可以预见地生产出高质量的产品，并且尽可能少地返工。他们将直接的利益相关者视为最密切参与这项工作的人：开发人员、部署人员、测试人员和分析师。

但架构师也将文档视为给自己带来价值。文件是保存重大设计决策结果的容器。一个经过深思熟虑的文档方案可以使设计过程更加顺利和系统化。无论是在六个月的设计阶段还是六天的敏捷冲刺阶段，文档都可以帮助架构师对架构设计进行推理，并在架构设计过程中进行沟通。

来源：susemm