您的组织可以在这里确保安全、隐私、可观察性等跨领域问题得到考虑。 这些通常是相对较短的部分，解释设计如何影响这些问题以及如何解决它们。 团队应该标准化这些问题。

由于其重要性，Google 项目需要有专门的隐私设计文档，并有专门的隐私和安全审查。 虽然这些审查只需要在项目启动时完成，但最好尽早与隐私和安全团队合作，以确保设计从一开始就考虑到这些。 对于这些主题的专用文档，中心设计文档当然可以只引用它们而不是详细说明。

设计文件长度

设计文档需要足够丰富和简洁，以便忙碌的人能够真正阅读它们。 较大项目的最佳长度是 10-20 页。 如果您的文档太长，最好将问题分解为可管理的子问题。 值得一提的是，写一份1-3页的“迷你设计文档”是绝对可行的。 这对于敏捷项目中的增量改进或子任务特别有帮助 - 您仍然可以像处理一个长文档一样处理所有步骤，只需保持简洁并专注于一组有限的问题即可。

3.什么时候不写设计文档

编写设计文档会产生一定的开销。 是否编写设计文档的决定归结为核心权衡，即围绕设计、文档、高级评审等建立共识的好处是否超过创建文档的额外工作负担。 这个决定的核心是设计问题的核心是否不明确——取决于问题的复杂性或解决方案的复杂性，或两者兼而有之。 如果设计问题的核心不模糊，写文档就没有什么价值。

如果设计文档实际上是一个实施手册，那么这清楚地表明设计文档是不必要的。 如果一份文档基本上只是说“我们是如何做到的”，而没有进行权衡、替代方案和决策解释（或者替代方案非常明显，不需要权衡），那么最好只写下实际程序。

最后，创建和审查设计文档的开销可能与创建原型和快速迭代不兼容。 然而，大多数软件项目确实存在一些实际的已知问题。 遵循敏捷开发方法并不是不花时间解决实际已知问题的借口。 或者，原型制作本身可以是创建设计文档的一部分。 “我尝试过，它有效”是选择设计的最佳论据之一。

4 设计文件的生命周期

设计文档生命周期的几个步骤是：

快速创建和迭代

审核（可能有多轮）

实施和迭代

维护和学习

快速创建和迭代

在此阶段，您将编写文档。 有时与作者团队合作撰写。

当文档与最了解问题领域的同事（通常在同一团队）共享时，这个阶段很快演变成快速迭代期，通过这个阶段他们澄清问题并提供建议，使文档成为第一个相对稳定的版本。 。

虽然您肯定会发现工程师甚至团队更喜欢使用版本控制和代码审查工具来创建文档，但 Google 的大多数设计文档都是使用 Google 文档创建的，并大量使用其协作功能。

审查

在审查阶段，设计文档会与原作者和密切合作者之外的更广泛的受众共享。 评论可以带来很多价值，但它们也是一个危险的陷阱，所以要明智地处理它们。

审核可以采取多种形式：一种更轻松的方法是将文档发送给（更广泛的）团队列表，以便每个人都有机会查看。 讨论主要发生在文档的评论部分。 更严肃的审查是正式的设计审查会议，作者将文档（通常是专门的演示文稿）呈现给更高级的工程师。 Google 的许多团队都会为此目的定期召开会议，工程师可以报名参与评审。 当然，等待这些会议召开可能会大大减慢开发进度。 工程师可以通过直接寻求关键反馈而不是阻碍更广泛的审查过程来缓解这种情况。

当谷歌还是一家规模较小的公司时，人们常常将设计发送到核心邮件列表，高级工程师在闲暇时审查这些设计。 这可能是处理公司事务的好方法。 好处之一是，这确实在公司中建立了一种相对非正式的软件设计文化。 然而，当公司规模扩大到相对较大的工程团队时，维持集中式方法就不再可行。

评审带来的主要价值是它们提供了将组织的综合经验纳入设计的机会。 最一致的是，审查阶段确保考虑到可观察性、安全性和隐私等跨领域问题。 评审的主要价值不在于识别问题本身，而在于在开发周期的早期识别问题写文件的软件，此时进行更改的成本仍然相对较小。

实施和迭代

当事情进展到您确信进一步审查将不再需要对设计进行重大更改时，就可以开始实施。 当计划与现实发生冲突时，不可避免地会出现缺陷、未解决的需求、经过深思熟虑的猜测最终被证明是错误的，并且需要进行设计更改。 在这种情况下，强烈建议更新设计文档。

一般来说：如果设计的系统尚未交付，请务必更新文档。 在实践中，我们人类不擅长更新文档，并且由于其他实际原因，更改通常会被自己放入新文档中。 这导致最终状态有点类似于美国宪法，带有一堆修正案写文件的软件，而不是一份连贯的文件。 从原始文档到这些修订文件的链接对于那些将来试图通过设计文档来理解目标系统的糟糕的维护程序员来说非常有用。

维护和学习

当谷歌工程师面对一个他们以前从未使用过的系统时，他们的第一个问题通常是“设计文档在哪里？” 尽管设计文档与其他文档一样，随着时间的推移可能会脱离现实，但它们通常仍然是了解创建系统的想法的最简单的切入点。

作为作者，1、2年后回顾一下自己，重新阅读一下自己的设计文档。 你做对了什么？ 你做错了什么？ 今天你会做什么来做出不同的决定？ 回答这些问题是作为工程师进步并随着时间的推移提高软件设计技能的好方法。

5 结论

设计文档是提高清晰度并就解决软件项目中最困难问题达成共识的好方法。 设计文档可以节省资金，因为它们允许进行预先调查，并避免编写无法实现项目目的的兔子洞； 设计文档也需要花钱，因为创建和审查设计文档需要时间。 因此，请为您的项目明智地选择！

在考虑编写设计文档时，请考虑以下事项：

如果您对其中 3 个或更多问题的回答为“是”，那么设计文档可能是开始下一个软件项目的好方法。

原文链接：