4.7 文档的最佳实践规则

与许多其他面向程序或技术的文档一样，有一些经过验证的规则适用于所有类型的架构文档。这些规则主要用于确保此类文档的可读性和适当性。

4.7.1规则1:从读者的角度写作

如果您不从读者的角度编写文档，他们会觉得自己的需求没有被认真对待。就其本质而言，文档更多是被阅读而不是被编写。 尽量避免过度使用技术术语（实际上，这始终是一种平衡行为）。特别重要的专业术语应单独解释 - 例如，在词汇表中。 您应该注意文档的结构，并将您的想法和思路整理成有建设性的顺序。再次，我们建议使用适当的文档模板。

4.7.2规则2:避免不必要的重复

如果重复确实有必要，应谨慎使用，并且只有在以下情况下: • 简化文档的使用 • 显著简化其维护和更新 当出现只有细微变化的重复时，问问自己以下问题： • 这种变化是有意的吗? • 应该重视这个变化吗? 请注意，从不同角度的文档不应被视为重复，因为它有助于加深对所记录内容的理解。

4.7.3规则3:避免歧义

架构文档常常对未来的设计决策保持开放（计划中的行动自由）。然而，架构规范中过度的解释自由很容易导致意想不到的歧义。

使用形式化描述语言有助于克服这一问题。但在实际中，这些语言仍然（太）少被使用。

如果使用符号标记（如 UML），您应该解释符号的含义或包含对单独解释来源的引用。

4.7.4Rule 4: 标准化的组织结构或模版

（标准化的）结构很重要，特别是当您经常创建架构文档时。它为您的读者提供了识别价值，并简化了引用（例如，“参见客户管理系统中的构建块视图”）。 一旦定义了结构，就应该向用户解释。预定义的结构还有助于保持对文档完整和不完整元素的概览。它也支持文档质量，因为文档要涵盖的所有方面都是预先定义的。

4.7.5Rule 5:书面说明重要决策的理由

为了帮助您的读者理解您的架构和设计，（简要地）说明重要决策的理由是有帮助的。例如，可以通过引用相关的公司政策来提供理由 - 例如：“对于 X 类型的应用程序，优先使用.NET 或 Java EE”或“客户主数据应仅存储在大型机上的中央客户数据库中”。

明确拒绝的替代方案以及解决方案的优缺点也可能是有意义的。例如，“使用内部开发的持久化框架可以增加灵活性，但与现有的框架（如 Y）相比，不值得承担相关的开发和长期维护工作。”

除此之外，这可以节省讨论的时间，特别是如果在新的情况下必须重新考虑决策。理由有助于您的读者理解您的决策以及为什么做出这些决策。

4.7.6Rule 6:检查文档的适合性

文档的一个重要方面是它对您的读者群在实际中的使用。在您最终发布文档之前，您应该让目标群体的合适代表进行审查，并将审查结果纳入文档。只有预期的用户群体才能决定是否以正确的方式提供了正确的信息。

审查过程本身也应该进行检查。您需要建立一个改进过程，定期检查您的文档策略是否存在缺陷。

4.7.7Rule 7:简洁的图表

另一个有用的规则（可以有合理的偏差）是避免过于庞大的图表。根据认知科学研究，人们在图表中能够有效处理的元素数量在 5 到 9 个之间（7 ± 2）。 请注意：在 4.6.5 节中描述的“架构壁纸”方法是此规则的明显例外。

4.7.8Rule 8:定期更新

引入一个在开发和维护工作期间定期更新文档的流程。 更新不充分 • 导致文档不完整 • 降低文档的效益和使用水平 • 阻止文档成为重要的信息来源，并导致不必要的询问 悬而未决的问题要求及时更新。然而，如果设计决策变化非常快，你就不应该过于频繁地更新;否则，你很快就什么都做不了了。等到尘埃落定后进行更新。为更新定义固定的同步截止日期是有用的。