记录产品设计决策依据的有效方法是什么？

在我们公司，我们不使用任何产品设计文件。我们共有三名员工，因此所有产品设计讨论都当面或在Slack上进行。（我们还在基本的Slack软件包上，该软件包仅允许查看最新消息。）

我们的产品仍处于早期阶段，我们经常重新访问几个月前确定的设计元素。

我们经常痛苦地面临的一个问题是忘记了为什么要做出产品设计决策。这导致浪费了数小时来重读相同的地面。

我们如何有效记录设计决策背后的基本原理？

我们的工作流程基于Pivotal Tracker。我想到的一种解决方案是，将所有相关设计决策的依据记录为对用户故事本身的评论，但这似乎并不可靠。

要100％清楚：我不是在谈论代码的设计。我说的是由代码实现的产品设计。换句话说，我不是在谈论诸如“我们应该使用合成而不是多重继承来构造这个类吗？”之类的决策。我正在谈论诸如“我们应该要求用户在登录之前确认用户的电子邮件地址吗？”之类的决定。

该文档的目的是允许企业查看做出决策的原因的记录，以帮助做出有关同一主题的进一步决策。

您可以通过记录下来来记录设计决策背后的基本原理。理想情况下，靠近要决定的项目（不是“用户故事”-用户故事是描述必须执行的内容，而不是如何执行的描述）。

特别是注释的用途-记录为什么特定的代码或结构看起来像它（我不是专门谈论代码注释）。如果您的设计主题是功能，请对该功能进行介绍性注释。如果是课程，请在课程开始时就基本原理发表评论。如果您有一堆都应该遵循相同结构的类，请向包含这些类的包中添加单独的设计文档（例如“自述文件”）。如果您的设计主题是UML图，请在图的描述部分添加注释。

IMHO设计文档可能有其价值，但是如果它们描述的内容与所描述的项目“相距太远”，则它们往往会很快变得不一致。因此，我的建议是将所有设计文档尽可能靠近所设计的物品。

仅当您要记录以交叉方式影响代码许多不同位置的设计决策时，才使用单独的文档。当您使用它们时，请尝试使它们成为代码库的一部分，并将它们放置在设计主题的相应层次结构级别上（因此，如果您对包含许多源代码文件的一个模块做出设计决定，请放置设计说明“在该模块中，但不在一个类文件中，不在一个对其他模块有效的“顶级描述”中，并且绝对不在SCCS之外的单独Wiki中。如果要记录一些“高级”，产品广泛的设计决策，那么最好使用顶层文档，但是请确保该文档停留在该抽象层次上。

考虑一种敏捷方法。我的意思是，如果您有时间资源和出色的写作技巧来写下您每个设计决策以及他们的基本原理，则只需记录所有内容。实际上，我假设您不在这个位置上。 敏捷方法可以帮助应对基本原理的关键挑战：直到以后，您通常才知道哪些基本原理是重要的。

让我们从整体的角度来解决这个问题。你们有您做出决定的理由。他们现在正陷入squishyware中，成为团队的大脑。尽管获得了大量信贷文件，但将基本原理存储在sqishyware中并不是很糟糕。作为一个物种，我们实际上真的很擅长记住重要的事情。这就是为什么每个大型公司都拥有“部落知识”的原因，即使那些公司试图记录所有这些部落知识也是如此。

现在你有问题了。您发现sqiushyware无法充分发挥其原理。认识到存在问题并确定需要解决的问题对您有好处！这并不总是容易的一步！因此，我们非常确定解决方案是将一些基本原理转移到文档中。但是，这还不够。我们永远不会忘记难题的后半部分，它是在您需要做出决定时将基本原理重新加载到squishyware中。我见过很多团队，他们记录着所有疯狂的事情，但实际上这些内容并不是为了帮助您做出正确的决定而组织的，因此即使写下来，他们最终也会忘记基本原理。

因此，您需要执行两个步骤。您需要从squishyware入手文档。然后，您需要确保文档组织得井井有条，可以在需要时将合理性带回squishyware！现在，我认为我们有足够的问题陈述来认识挑战所处的位置。当您进行记录时，通常您不知道稍后将要看谁，或者他们在寻找什么。同样，回顾文档时，您通常不知道要查找的内容（最多可能知道何时）。

因此，大公司可能会尝试在两个大块中处理这个问题。首先，他们可能会根据人们在研究文档时的需求来制定需求。然后他们使用这些要求来构建用于开发所述文档的过程。而且，如果我敢说的话，那么每个人都会抱怨，因为几乎没有人确切地知道第一天的文档外观。文档总是不完整，开发人员总是抱怨该过程太繁琐。

是时候敏捷了。

我的建议是开始做出敏捷的努力来改善您的文档编制过程：从squishyware到文档再到sshyshyware整个九码。预先意识到您将丢失一些信息，因为您的流程不完美，但这没关系，因为您仍在尝试找出流程！如果您尝试创建一种适合所有解决方案的尺寸，则会怀念更多。

我会看一些特别的花絮：* 探索非正式文档。 正式文档很棒，但是很费时间。文档的目的之一是从开发者squishyware发布信息并将其放在纸上。非正式文档可将这样做的成本降至最低。

• 接受不可靠的文档格式。 第一次没事对。最好获取数据并弄清楚以后如何使其可靠。例如，您可以在<rationale> </ rationale>块或类似内容中记录您的基本原理，这将使以后收集数据变得容易。现在，将基本原理存储在用户故事中就可以了！
• 永远不要忘记组织的价值。 找出您作为一个团队如何喜欢在文档中搜索基本原理，并尝试以此为基础进行文档编制。每个团队都有不同的流程。在我的一个团队中，我们永远找不到符合其基本原理的机票。我们所能做的就是找到重要的代码行，执行一次操作svn blame，找出更改的时间和原因，然后查看票证。到达那里后，我们通常会在机票上正确填写我们需要的所有理由。刚刚为我们工作，找出适合您的方法。
• 有机文档会随着时间而增长。 对于开发人员而言，很少需要知道每天编写哪些基本原理最重要。我们通常会在以后找出哪些是重要的。如果您有一个整理文档的过程，使开发人员可以管理自己的一点点原理，那么重要的原理就会浮出水面。更重要的是，理由可能会改变。您可能会意识到，使用两个基本原理的两个不同的更改实际上是由对两者都适用的单个基本原理最好地描述的。现在，您与决策之间的内容越来越少了！

我建议设置MediaWiki或某些类似Wiki软件的私有实例。在此组织和重新组织内容真的很容易，您可以将新的讨论直接复制并粘贴到相关Wiki文章的“讨论”选项卡中。在上一份工作中，我们使用MediaWiki处理所有的体系结构和API文档，这是一个救命稻草。

从要求在12个月内更改它的编码器的角度考虑它。

如果您将此业务规则添加为自动测试，则将进行更改，然后从失败的测试中获得矛盾的要求（并希望您捕获与原始要求相关联的人员及其指定理由）。

我认为设计文档（放置BPMN图，事务图甚至是白板照片的地方）与代码相似，只是一种不可执行的形式……这意味着您要尝试的内容记录类似于代码注释，但是在设计中预先指定了（可测试的）要求。大概如果您是一家敏捷商店，您仍然可以设计代码，那么您只需在编写代码的最后一刻就完成代码。将其与所有其他项目文档一起保存在代码库中。

无论做什么，请确保以可搜索的方式存储它（例如，在指定新更改时，您可能希望提取与“身份验证”相关的所有业务规则）。

与往常一样，当您写东西时，您必须问自己自己是谁。我坚信设计文档适用于我的同行开发人员，无论是现在还是将来的开发人员。该文档可帮助他们了解我正在构建的内容或构建的内容（高级概述），更重要的是为什么。在这里可以记录您考虑的替代方案，每种方案的优缺点。

说某种设计可以存在于人们的大脑中是可以的，这可以避免开发人员继续前进并找到不同的工作，并带走了他们宝贵的信息。

将代码作为唯一的设计文档就像使用放大镜在城镇中寻路一样。地图要有用得多（不幸的是，没有与源代码等效的GPS）。

我同意设计文档比代码更容易腐烂。而且由于这两者之间无法进行验证，因此您唯一可以做的就是将它们保持紧密联系。IMO，过时的设计文件仍然提供了有价值的信息。