设计文档作为敏捷的一部分

在我的工作场所，我们面临的挑战是“敏捷”常常意味着“含糊的要求，不良的接受标准，好运！” 我们正在努力解决这一问题，作为一项总体改进工作。

因此，作为其中的一部分，我建议我们生成设计文档，这些文档要超出用户故事级别，并且能准确反映对系统中给定功能的效果进行初步调查的结果，并包括对我们所遇到问题的解答问生意。

有没有有效的标准呢？

我们目前面临的情况是，一项新功能可能会影响我们的“大泥巴”系统中的多个区域，并且由于这种技术债务，估计开始上升。希望更多周到的设计过程可以提供帮助。

“含糊的要求，不良的接受标准，祝您好运！”

是的，即使您也尝试将其确定下来，这也是您获得的相同要求！（例如，花费10,000美元的需求文档花费了政府客户4年的创建时间，仍然充满了不一致，含糊甚至内部矛盾的陈述。如果4年的需求文档不能使您获得像样，准确的需求，您是否曾经想过可以得到任何含糊的内容？）

因此...发明了一种敏捷方法来了解这种情况的发生并与其一起工作，而不是试图与之对抗。

您首先询问“您想要什么”，然后客户回答“有点类似”。您做了一些工作，然后回到客户那里说“这就像您想要的吗？”，而客户通常说“是，但是...”，然后您问“您想要什么”。

最终，即使他们不知道那是什么，您也能确切地获得客户想要的东西！（地狱，他们从不知道自己想要什么，不完全是）。

在我们的团队中，自敏捷以来，我们还一直在尝试缩小范围并了解实际需要多少文档。我可以与您分享我们到目前为止所学到的知识。

在进行其他任何操作之前，请务必先阅读敏捷/精益文档上的这篇文章。很好读。

其次，我强烈建议您在故事的初步工作之后重新考虑制作设计文档。我们之前曾尝试过，事实证明这是浪费。在上一发行版的中间，我们决定仅在提供故事代码后才更新设计文档。现在我在想，这还为时过早。

您需要问自己为什么要在编码之前做设计文档。对我们来说，这些是原因：

1. 我们作为一个团队需要了解故事将如何影响设计。
2. 当新的（或临时的）成员加入团队或返回到一年多没有工作过的代码时，拥有设计文件被证明是有用的。因此，它们对于组织存储很有用，有助于理解代码的工作方式。
3. 设计文档对维护工程师很有用，他们可能需要在发布后对代码进行故障排除。

满足（1），您无需产生实际的设计文件。您的团队在编码之前仍然应该有一个设计阶段，但是该阶段可以像在白板或餐巾纸上进行15分钟的会议一样简单。您无需编写实际的文档就可以讨论设计更改，而实际的文档将花费数小时（如果不是几天的话）。

在当前故事的开发过程中不需要（2）或（3），很有可能在随后的多个迭代中也不需要它们。

还请记住，每当团队成员编写/更新设计文档时，即是不编写代码的时候。当您在实际代码之前编写文档时，几乎有100％的机会需要更新文档，因为一旦开始编码，设计总是最终被更改。而且，即使您在代码后编写设计文档，正如我们的团队所了解的那样，从后续故事中进行重构仍然会改变设计。

所以我建议：

1. 最初产生足够的临时设计/模型，以便您的团队可以在编码之前进行明智的对话。不要指望保留这些内容，也不要浪费时间将它们正式化。
2. 仅在有人需要时才提供官方设计文档（即，您的团队确实需要组织记忆）
3. 仅针对已稳定的代码生成设计文档。试图记录每次迭代中不断变化的模块是没有意义的。
4. 制作完整描述模块（或产品的一部分）的设计文件。过去，我们曾经编写过设计文档，其中记录了必须进行的更改。发布完成后，这些文档完全一文不值。
5. 保持文档非常高级。如果您撰写20页的内容涵盖体系结构和非常高级的设计，则该文档将a）实际上被其他人阅读，并且b）将帮助人们熟悉您的代码的一般布局。有关详细信息，人们可以直接进入代码。如果您编写700页的详细规格说明，它们几乎总是与现实不符，那么任何人都将无法阅读，并且最终您将不得不维护和更新700页而不是每当将来进行更改时要更新20页。

敏捷的“口头禅”并非完全没有文档。

敏捷的口头禅是“ 工作软件胜于全面的文档 ”。但请注意宣言底部的内容。

也就是说，尽管右边的项目有价值，但我们更重视左边的项目。”

鲍勃叔叔有一个很好的文件记录政策

除非需要立即且重要，否则不产生任何文档。

没错，有些人以敏捷为借口而不制作文档，但这是不好的敏捷。它忽略了我在上面引号中突出显示的位。

综上所述，当您说“我们当前面临的情况是，一项新功能可能会影响我们的“大泥巴”系统中的多个区域”时，如果您要变得敏捷，则需要对此做些事情。

当您拥有文档时，可使用它来模块化您的代码。这样，您就可以通过消除对文档的长期需求来消除维护文档的长期需求（不会发生）。

即。使需求变得迫在眉睫。

关于敏捷的问题是，文档工作确实必须由Scrum团队来推动。如果开发人员认为外部文档不足以满足他们的需求，那么用户故事将被阻止，直到他们这样做为止。如果企业认为开发人员没有提供足够的文档，则产品所有者坚持将其纳入验收标准。因此，自转向Scrum以来，我实际上发现我们的文档更加集中和有效。

我们使用VersionOne跟踪我们的用户故事，但是我确定我们的方法适用于其他系统。它使您可以将文件附加到用户故事。我们发现这是放置设计文档的非常有用的地方。

举一个对我们来说非常有效的例子，我们需要在原型制作后尽快测试一种新的电路板设计。我们为需要测试的所有内容制作了两个用户案例：一个用于设计测试，另一个用于执行测试。设计故事的一项接受标准是测试过程已在执行故事中完整记录。

当我们进入测试部分时，它比我所见过的更加顺利。我们只是打开了用户故事，并按照逐步的步骤进行操作。文档正是我们完成故事所需要的，没有更多也没有更少。

我们的积压订单中还有一个故事，就是要改进我们使用的芯片的文档，以使其他团队更轻松地为自己的产品取货。

总而言之，如果您觉得自己的文档很痛苦，那么解决方案就像为它创建单独的用户故事和/或使其成为接受标准的一部分一样容易。

当您谈到较差的要求时，对我而言，第一件事就是确保您具有测试标准。如果可能，请为系统的现有部分创建一些可重用的自动化测试用例。一旦每个人都适应了，那么就可以在编写代码之前着手编写测试用例。好的测试用例可以很好地记录系统的行为。

至于使用哪些特定的设计文件，正如其他人已经说过的那样，它很大程度上取决于团队的需求以及他们将要承担的下一个任务。在可能的情况下，尝试使用可以从您的文档中生成代码的工具，或从文档中生成代码的工具。文档维护可能变得非常昂贵，因此在保留设计文档时应明智地选择。

就个人而言，我从代码和fitnesse测试用例生成的类图上都取得了成功。团队打印出几个类图，与产品负责人进行标记会议，然后从那里制定一个估算。就fitnesse而言，我很幸运地与几个产品所有者合作，他们非常擅长在电子表格中表达他们想要的东西，然后将其转换为适合fitnesse的表。