设计文件中应包含对给定设计的利弊的讨论，还是应集中于事实和理由？

我目前正在更新设计文档，以使其对未来的开发人员来说是正确的和最新的。

当前，该文档仅关注事实，介绍设计的方式。提出的任何决定都没有理由。我认为，掌握基本原理很重要，这样开发人员才能知道事情为什么如此，因为这很可能会影响未来的决策。对于我来说，不可能为所有设计决策（尤其是在我开始从事该项目之前所做的决策）添加依据，但是我正在本部门尽我所能。

但是，考虑到项目的要求，某些设计决策是非常糟糕的决策。不过，也有一些不错的。

我最初的想法是，我应该讨论设计问题以及针对这些问题的潜在解决方案或变通办法，以引起未来维护者的注意，但是我不确定设计文档是否适合进行此类讨论和提供信息。我不希望其他人在该系统上工作并更新文档时使设计“批判”猛增到“撕毁该设计的新特性”，因为这显然是不合适的。

我的经理会支持任何一个决定，所以这取决于我。无论采用哪种方法，生成的文档都将进行正式版本控制，并通常在执行开发任务之前将其提供给系统上的开发人员。期望新的开发人员在开始开发工作之前先熟悉与给定软件系统相关的文档。

问题：

• 设计文件应遵循原始事实（“这就是设计”）和基本原理（“这就是设计的原因”）还是应该用于指出设计中可能存在问题的无缺陷问题未来的开发商？
• 如果不应该使用设计文档来捕获这些信息，那么应该通过讨论设计原理，权衡和已知问题（不是缺陷，因为可以跟踪缺陷）的讨论，应该捕获哪种类型的文档，以及应该捕获什么其他类型的文档？使用其他工具）？

如果优缺点可以用一两句话概括，那么可以将它们放入设计文档中。更长的时间应该分开。

在我目前工作的地方，通常会有一个单独的“设计决策”文档来跟踪所有重大决策。通常用描述问题的段落进行格式化（例如“在每个处理周期结束时，某些文件需要从服务器移至某些用户，有许多方法可以执行此操作...”），该表带有列“解决方案说明”（例如“通过FTP移动文件”），“优点”（例如“易于用户管理”），“缺点”（例如“不够安全以符合ABC-XYZ”）和得出以下结论：解释了为什么选择了特定的决定（例如“将不使用FTP，因为它将无法满足某些合规性要求”）。设计文档通常只引用所选的决策，

设计文件应遵循原始事实（“这就是设计”）和基本原理（“这就是设计的原因”）还是应该用于指出设计中可能存在问题的无缺陷问题未来的开发商？

不是“非此即彼”。

没有人首先阅读文档。他们脱脂-充其量。因此，请写尽可能少的文件。一个文件是任何人都耐心的。带有“其他问题”的第二个“非目标”文档根本不可能被阅读。

一个文件的优势？人们可能会读它。

一个文件的缺点？很少 大多数情况下，它已经过时了。

多重文件的优势？没有。

多个文件的缺点？请阅读有关DRY原理和识字编程的内容。多个文档意味着多种错误来源。每个文档都彼此不同，也不同意代码。这是很明显的。这是疯狂的道路。

避免用手拧。

利弊文档可以无限期深入进行假设分析和有吸引力的麻烦讨论。

如果您觉得有必要提出优点和缺点，请简明扼要。

专注于什么。

保持不裸露的东西。

如果您已完成基准测试，研究或实际探索的替代方法，请记录下来。但是，如果您只是在考虑替代方案，请将其最小化。

这不应该是您经历磨难的个人经历。

• 有问题吗？固定它？花了几周？真的很挣扎吗？很少是有趣的轶事。它在代码中固定。以前的版本，错误的版本，错误的版本和低性能的版本都无关紧要。他们充其量是博客爱好者。

• 还有问题吗？不固定？这意味着还有其他选择。记录下来。

决策过程中有3个重要事实：

• 尝试过但不起作用的原因（以及为什么不起作用的原因，因为您的目标是移动目标）
• 什么是
• 可能是什么（只是等待X得以实现...）

但是，除了“什么是”之外，其他所有内容都会使读者感到困惑，并阻止她迷惑系统。

我喜欢捕获另外2个的想法，尽管它们对于学习系统不太有趣，但在更改系统时可以节省时间。

因此，我将在暴露@FrustratedWithFormsDesigner的想法基础上进行一些改动。我将创建一个附件部分，而不是创建具有其自身生命周期的另一个文档。然后，对于每个值得讨论的决定，我都将指出附件中的相关条目。

是。设计文档应说明与所描述的设计相关的收益，风险和假设。设计文档具有以下目的：

1. 将设计写下来，以便每个人都可以理解，并且每个人的理解都不会随时间推移而变化。

2. 与从事该项目的非技术人员交流设计。

3. 协助安排，资源分配，成本估算和其他类型的计划。

4. 成为整个项目文档的重要组成部分。当您加入进行中的项目或必须维护已完成的项目时，如果有一个设计良好的设计文档，则工作会容易得多。

5. 通常是合同要求的可交付成果之一。

（可能还有其他人，但这是一个好的开始。）

设计文档可以很好地满足这些目的中的每一个，这些文档清楚地说明了为什么选择此设计以及相关的风险是什么：

1. 至关重要的是，团队中的每个人都知道风险和收益是什么，以便他们可以共同努力避免这些风险并充分利用设计的收益。

2. 对于非技术团队成员，了解风险和收益通常比设计本身的细节更为重要。

3. 风险管理是项目经理要确保成功所能做的最重要的事情之一，第一步是确定需要管理的风险。应该由经理来决定如何处理风险，但是设计者有责任指出设计中的已知风险。

4. 即使风险不再是问题，将其记录在文档中也通常会很有用，因为它可以帮助解释设计创建时的情况。这样一来，维护人员就可以做出类似的决定：“好吧，他们那时就这样做了，因为...但这不再是问题，因此我可以用更简单，更快的实现方式替换该代码。” 当然，同样的好处。

5. 如果您正在为客户进行项目，那么记录风险和收益就尤为重要。这使客户注意到，在某些情况下可能会出问题，或者要求更改设计可能会损害某些承诺的好处。

我从一个问题中得知，您正在使用现有的设计文档来处理已经实现的系统。在这种情况下，许多可能的风险不再是风险，因此事后对其进行记录没有太大意义。但是，您现在具有事后观察的优势，因为您可以看到原始设计中效果欠佳的部分。我认为您应该：添加单独的部分来标识当前的问题区域并提出解决方案（包括相关的风险！）；或创建执行相同操作的单独文档。这个新的部分/文档可能会演变成该软件下一版本的设计文档。

这是有关编写设计文档的博客条目，您可能会发现有帮助。

如果有合理的理由要避免使用更明显或标准的解决方案，则应注意这些原因。您可以为别人省很多麻烦。但是，特定技术可能会随着时间的推移而改进，因此您的理由可能不适用。然后，将来的开发人员可以使用自己的判断。

我不知道指出所有缺点是否有很多好处。进行更改或将发生其他优先级可能不切实际。您可能会在不久的将来修复其中的一些，这将是更新的另一件事。

我个人不会将其放入设计文档中。设计文档应概述外观，而不是外观。

如果您非常需要关于为什么设计是这样的背景故事，也许您应该将其写在Wiki文章（或您的公司使用的任何知识库）中，以便可以有一个历史记录。设计的演变。人们可以去阅读，编辑和添加建议。这样，它更像是一个公开的讨论，而不是眉头敲打文档。

我同意您在设计文档中加入基本原理的意见。

无论如何，

在更新别人编写的设计文档的过程中，我会保持谦虚的态度，不要试图猜测为什么要做出这样的决定。

所以，

我只会插入有关维护期间设计中所做更改的基本原理。