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

Question

在我们公司，我们不使用任何产品设计文件。我们一共有三名员工，所以所有的产品设计讨论都是面对面的，或者是在斯拉克。(我们还使用了只允许查看最新消息的基本Slack包。)

我们的产品还处于初级阶段，我们经常会重新审视几个月前决定的设计元素。

我们经常面对的一个问题是忘记了为什么会做出产品设计决策。这导致几个小时浪费在同一块土地上。

我们如何有效地记录设计决策背后的理据？

我们的工作流程是基于关键跟踪器的。我想到的一个解决方案是将所有相关设计决策的理据记录为用户故事本身的注释，但这似乎不可靠。

要100%明确:我不是在说代码的设计。我指的是由代码实现的产品的设计。换句话说，我不是在说“我们应该使用组合而不是多重继承来构造这个类吗？”；我指的是“我们应该要求用户在登录前确认他们的电子邮件地址吗？”

文档的目的是让企业查看作出决定的原因的记录，以帮助就相同的主题作出进一步的决定。

Answer 1

你记录设计决策背后的理由，把它们写下来。理想情况下，在受决策约束的项目附近(这不是“用户故事”--用户故事是必须实现的内容，而不是如何实现的描述)。

这尤其是为了记录为什么一个特定的代码或结构看起来是这样的(我并不是专门谈论代码注释)。如果您设计的主题是功能，请对该功能进行介绍性评论。如果是类，请在类的开头对基本原理进行评论。如果您有一组类，它们都应该遵循相同的结构，那么向包含这些类的包中添加一个单独的设计文档(比如“自述”文件)。如果您的设计主题是UML图，请向图的描述部分添加注释。

IMHO设计文件可能有其价值，但如果它们描述的东西太“远离”它们所描述的项目，它们往往很快就会变得不一致。因此，我的建议是将任何设计文档尽可能接近设计项目。

仅当您希望以交叉方式记录影响代码许多不同位置的设计决策时，才使用单独的文档。使用它们时，尝试将它们作为代码库的一部分，并将它们放置在设计主题的相应层次上(因此，如果您为一个模块(由多个源代码文件组成)作出设计决策，请将设计描述“放在”该模块内，而不是放在一个类文件中，而不是放在对其他模块有效的“顶级描述”上，而且肯定不会放在SCCS之外的单独的Wiki中。如果您想要记录一些“高层次”的产品范围的设计决策，那么顶级文档可能是最好的地方，但是要确保该文档保持在抽象级别上。

Answer 2

考虑一种敏捷的方法。我的意思是，如果你有时间资源和优秀的写作技巧，写下你的每个设计决策和他们的理由，只需记录一切。实际上，我假设你不是这样的人。敏捷方法可以帮助您解决理据文档方面的一个关键挑战:您通常直到稍后才知道哪些理由是重要的。

让我们从整体的角度来看待这个问题。你们的决定是有道理的。他们现在被困在鱿鱼里了，团队的大脑。尽管获得了大量的信用文件，在sqishyware中存储理据并没有那么糟糕。事实上，作为一个物种，我们很擅长记住重要的事情。这就是为什么每个大公司都有“部落知识”，即使这些公司试图记录所有的部落知识。

现在你有麻烦了。你会发现，斯丘什陶器并没有足够好地抓住这些理由。这对你来说是件好事，因为你意识到了问题的存在，并发现它需要解决！这并不总是容易的一步！因此，我们非常肯定，解决方案是将其中一些基本原理卸载到文档中。然而，这还不够。我们永远也忘不了谜题的后半部分，当你需要做出决定时，它是将原理重新加载到squishyware中。我见过很多团队都会疯狂地记录每件事，但这些内容实际上并不是为了帮助做出正确的决定而组织起来的，所以他们最终会忘记理由，尽管它们被记录下来了。

所以你有两个步骤。您需要从squishyware中获取基本原理，并将其转化为文档。然后，您需要确保文档组织得足够好，以便在需要时将rational带回到squishyware中！现在，我认为我们有足够的问题陈述来认识到挑战的方向。当您正在进行文档记录时，您通常不知道谁将稍后查看它，也不知道他们在寻找什么。同样，当您回顾文档时，通常不知道您在寻找什么(充其量您可能知道什么时候)。

因此，一家大公司可能会试图在两个大街区内处理这件事。首先，他们可以根据人们在研究文档时需要什么来开发需求。然后，他们使用这些需求来构建一个开发上述文档的过程。而且，如果我敢这么说的话，那么每个人都会抱怨，因为几乎没有人知道第一天的文档应该是什么样子。文档总是不完整，开发人员总是抱怨这个过程太累赘了。

是时候敏捷了。

我的建议是启动一种敏捷的方法来改进您的文档过程:从squishyware到document，再到squishyware，一共9码。预先认识到你会失去一些信息，因为你的过程并不完美，但这没什么，因为你还在努力弄清楚这个过程！如果您试图创建一个适合所有解决方案的统一大小，您会错过更多。

我想看几个特别的小贴士：*探索非正式文档。正式的文档是伟大的，但它的时间消耗。文档的目的之一是从开发人员squishyware中发布信息并将其写在纸上。非正式文件将这样做的费用保持在最低限度。

• 接受不可靠的文档格式。第一次什么都不会对。更好的办法是得到数据，并找出以后如何使其可靠。例如，您可能会将您的理据记录在一个<基本面>块中，或者类似的东西中，这样以后就可以轻松地获取这些数据。存储在用户故事中的理据，就目前而言，是好的！
• 永远不要忘记组织的价值。找出作为一个团队，你喜欢在文档中寻找理据的方式，并尝试对此进行文档化。每个团队将有一个不同的过程。在我的一个团队里，我们永远也找不到一张有理由的罚单。我们能做的就是找到一行重要的代码，做一个svn blame来找出它什么时候变了，为什么，然后去看看票。一旦我们到了那里，我们通常会把我们所需要的所有理由都写在票子上。这对我们有用，找出什么对你有用。
• 有机文档可以随着时间的推移而增长。开发人员很少知道什么理由是最重要的一天，他们需要写它。我们通常会发现哪些是重要的。如果您有一个整理文档的过程，允许开发人员管理他们自己的小理性主义花园，那么重要的部分就会浮出水面。更重要的是，理由可能会改变。你可能会意识到，两种不同的变化，有两种不同的理由，最好是用一个对两者都适用的理由来描述。现在你和决定之间的内容少了！

Answer 3

我建议设置一个MediaWiki或类似的wiki软件的私有实例。在那里组织和重新组织内容非常容易，您可以将新讨论直接复制并粘贴到相关wiki文章(S)的“讨论”选项卡中。我们在上一份工作中使用了MediaWiki作为我们所有的体系结构和API文档，这是一个救生器。