The following text is a partial translation of the original English article, performed by ChatGPT (gpt-3.5-turbo) and this Jekyll plugin:
有一本名为《软件需求》的好书，作者是卡尔·威格斯，讲述的是关于软件需求的内容。在我看来，每个软件工程师都应该读一读。我不需要重复书中的内容，但我们在规范中经常犯一些非常简单而典型的错误。我一次又一次地在我们的文档中看到这些错误，这就是为什么我决定总结它们的原因。所以现在，我将总结一下，从程序员阅读规范文档的角度来看，其中最重要和最典型的十个错误。
《IEEE 830-1998》的第4.3章指出，一个好的《规范》应该是正确、明确、完整、一致、排序、可验证、可修改和可追踪的。总共有八个质量要求。然后，该标准用相当简单的英语逐一解释了它们。但我们有时间去读那些无聊的标准吗？那些是给大学教授和认证机构用的。我们是实践者，天哪！…等等，我在开玩笑。
无论项目有多小，我们有多实际，总会有一个解释需要完成什么工作的文档，它可以被称为《软件需求规范》，或者只是简称为《规范》。当然，有很多创造空间，但我们是工程师，而不是艺术家。我们必须遵循规则和标准，主要是因为它们使我们的沟通更容易。
现在，我要进入正题了。我通常看到的规范基本上违反了前面提到的所有八个原则。下面是它们是如何做到的详细总结。顺便说一句，所有的例子都是来自真实的商业软件项目中的真实文档。
How about this:
UUID is set incrementally to make sure there
are no two users with the same account number.
UUID和账号之间有什么区别？它们是同样的东西吗？看起来是这样的，对吗？或者它们是不同的…知道UUID代表什么就好了。它是“唯一用户ID”还是“统一用户身份描述符”？我不知道。我迷失了，我想找到这篇文章的作者并对他或她做些坏事…
我已经写过了，最糟糕的技术规范没有词汇表。根据我的经验，这是所有需求文档中最大的问题。它不是散文！不是情书！它是技术文档。我们不能为了好玩而玩弄词语。我们不应该只是为了表达自己而使用产品规格。我们写作是为了被理解，而不是给读者留下印象。和图表一样，如果我不理解你，那是你的问题。
这是文本经过适当改写后的样子：
Better now?
因此，第一个也是最大的问题是过于肤浅地使用术语和文字，而没有在词汇表中对其进行预定义。
我最近在产品规格中看到过这个。
是的，这段文字在需求文档中原封不动地存在。首先，作者表达了他个人对主题的看法。然后，作者问我是否有可能的选择。然后，他建议我考虑一些事情，之后邀请我进行讨论。
令人印象深刻，对吧？显然，作者有非常有创造力的个性。但是我们应该尽可能远离这个人参与项目文档的工作。这不是需求文档所欣赏的内容。当然，我们欣赏创造力，但是这四件事是严禁的：问题、讨论、建议和意见。
规格说明中不能有任何的“问题”。这些问题是针对谁的？我，作为一个程序员？我是应该实现软件还是回答你的问题？我对与你一起集思广益不感兴趣。我期望你作为需求作者告诉我需要做什么。在撰写文档之前找到所有答案。那是你的职责所在。如果你没有答案，可以写上“待确定”。但是不要问问题。那很烦人。
需求文档不是一个“讨论”版。作为规范的读者，我期望能看到需要做什么，不带任何“可能”或“我们可以另外做”。当然，你需要讨论这些问题，但是在撰写文档之前请先讨论。在其他地方讨论，比如在Skype、Slack上或者通过电子邮件。如果你真的想在文档中讨论，可以使用带有版本跟踪功能的Google Docs或Word。但是讨论结束后，请从文档中删除讨论历史。它只会让我这个程序员感到困惑。
也没有必要将需求格式化为“建议”。只需直接说明需要做什么以及软件如何工作，无需担心出错。通常，人们在害怕直接说出来时会采用建议。例如，不是说“应用程序必须在Android 3.x及更高版本上工作”，而是说“我建议使应用程序与Android 3.x及更高版本兼容”。看到区别了吗？在第二个句子中，作者试图回避个人责任。他没有明确说“确切的是Android 3.x”；他只是提出建议。不要胆怯，直接说出来。如果你犯了错误，我们会纠正你的。
当然，“意见”也一点也不受欢迎。这不是写给朋友的信件，而是属于项目的正式文件。几个月或几周后，你可能会离开项目，其他人会继续使用你的文档。规范是项目发起人与项目团队之间的合同。文档作者的意见在这里并不重要。与其写上“Java似乎会更快”，并建议“我们应该使用它”，不如说“Java更快，所以我们必须使用它”。显然，你写这句话是因为你这样认为。但是一旦写在那里，我们不关心它来自谁以及你对这个问题的想法。这些信息只会让我们更加困惑，所以省略它。只有事实，没有意见。
别误会，我不反对创造力。程序员不是机器人，默默地实现文档中写的内容。但是一个混乱的文档与创造力无关。如果你希望我创造，就定义创造力的限度，并让我在其中进行实验；例如：
这就是你邀请我发挥创造力的方式。我意识到产品的用户对API中的版本控制机制并没有真正的理由或期望。我可以自由发挥。太好了，我会按照自己的方式去做。
但是请再次强调：规范不是一个讨论板。
这是它的外观：
这是我在几乎每个规范中都看到的典型错误。在这里，我们混合了一个功能需求（“滚动图像”）和一个非功能性需求（“滚动流畅且快速”）。为什么这是不好的呢？嗯，没有具体的原因，但它显示了一种缺乏纪律性的表现。
这样的需求很难验证或测试，很难追踪，也很难实现。作为一个程序员，我不知道什么更重要：滚动还是确保滚动快速。
此外，修改这样的陈述也很困难。如果明天我们添加另一个功能需求——例如滚动好友列表——我们还会希望要求这个滚动也是平滑且快速的。然后，几天后，我们还想说“快速”意味着小于10毫秒的反应时间。然后，我们将不得不在两个地方重复这些信息。看看我们的文档最终可能变得多么混乱？
因此，我强烈建议您始终单独记录功能和非功能性需求。
这与以前的问题类似，可能是这样的：
很明显，这段文字描述了两件事情。第一是用户可以下载一个PDF报告。第二是这个报告应该是什么样子的。第一件事是一个功能要求，第二件事必须在一个补充文档（或附录）中进行描述。
总的来说，功能要求必须非常简短：“用户下载”，“用户保存”，“客户请求并接收”等等。如果您的文本变得过长，那就有问题了。请尝试将其中的一部分移到一个补充文档中。
这就是我所说的内容：
我可以通过查看我在过去几年中见过的许多项目的需求规范来找到更多的例子。它们看起来都一样。问题总是一样的：很难定义一个真正可测试和可衡量的非功能性需求。
是的，这很困难。主要是因为有很多因素。以这个例子为例：“应用程序必须在2秒钟内启动。”在什么设备上？用户配置文件中有多少数据？“启动”是什么意思；它是否包括配置文件加载时间？如果存在启动问题怎么办？它们算吗？有很多类似的问题。
如果我们回答了所有这些问题，需求文本将填满整个页面。没有人希望如此，但拥有不可衡量的需求是更大的问题。
再次强调，这并不容易，但是很有必要。尽量确保所有质量要求都完整且没有歧义。
这个例子说明了一个非常常见的陷阱：
这是微观管理，对于需求分析师来说，他们不应该这样对待程序员。你不应该告诉我如何实现你想要的功能。你想要让用户通过Facebook登录？就这样说。你真的关心它是通过按钮点击还是其他方式实现吗？你真的关心我在数据库中存储什么吗？如果我使用文件而不是数据库，这对你来说重要吗？
我不这么认为。只有在非常罕见的情况下，这才会有影响。大部分时候，这只是微观管理。
规格说明书应该只要求真正关乎业务的内容。其他所有的事情都由我们程序员来决定。我们决定使用哪个数据库，按钮放在哪里，以及在数据库中存储哪些信息。
如果你真的关心这个，因为有某些更高级别的限制 - 就这样说。但再次强调，不要作为对我们程序员的实施指令，而是作为像这样的非功能性需求：
重点是，我对需求没有任何意见，但我强烈反对实施指导。
这段文本可能看起来像：
这里的问题是没有“参与者”。这个功能或多或少是清楚的，但是不清楚是谁在做所有这些事情。用户在哪里？这只是一个发生在某个地方的故事。这并不是程序员实施所需的。
解释功能的最佳方式是通过用户故事。而且一个好的用户故事总是有，猜猜是什么…一个用户。它总是以“用户…”开头，后跟一个动词。用户下载，用户保存，用户点击，打印，删除，格式化等等。
用户不一定是人类。它可能是一个系统，一个RESTful API客户端，一个数据库，任何东西。但总是有一个人。”有可能下载…“不是一个用户故事。这对谁有可能？
How about this:
Our primary concern is performance and an attractive
user interface.
这是噪音。作为这份文件的读者，我既不是投资者也不是用户，而是一名程序员。我不关心你在这个项目中的“主要关注点”是什么。我的工作是根据规格实现产品。如果性能是你的主要关注点，就给我提供可衡量和可测试的需求。我会确保产品满足这些需求。如果你无法提供需求，请不要用这些无关紧要的信息来骚扰我。
我不想分享你的关注点、信念或意图。那是你的事情。你的工作就是将这一切正确明确地翻译成可测试和可衡量的需求。如果你做不到这一点，那是你的问题和你的错。不要试图让它变成我的问题。
很多时候……等等。非常、非常多时候。不对。几乎总是。错了，总是！没错，规格文件总是充满噪音。有些噪音少一点，有些多一点。我认为这是懒惰和不专业的文件作者的症状。在大多数情况下，只是懒惰。
他们不想思考和将他们的关注点、想法、思考、意图和目标转化为功能性和非功能性需求。他们只是将它们放入文件中，希望程序员能够找到正确的解决方案。好的程序员应该知道什么是良好的性能，对吧？我们只需告诉他们性能是我们关注的问题，他们就会想出办法。
不！不要这样做。好好完成你的工作，让程序员来完成他们的工作。
作为程序员，我们绝不应该接受这样的文件。我们应该直接拒绝并要求需求作者重新进行工作并消除噪音。如果一个产品的规格中有很多噪音，我建议甚至不要开始工作。
这是又一个非常典型的错误：
看起来很混乱吧？有三个不同的观点，而且都不适合作为规范文档。规范必须描述产品就像它已经存在一样。规范必须听起来像是一本手册、教程或参考资料。这段文字必须重新编写成这样：
看到区别了吗？所有的“必须”，“需要”和“将会”这些词只是为文档增加了疑虑。对于这份规范的读者来说，“API将会支持”听起来就像是“可能在未来某个时候，也许在下一个版本中，它将会支持”。这不是作者的意图，对吧？不应该有疑虑，没有双关意义，也没有可能性。API就是支持的。就这样。
我可能忘记了一些重要的事情，但这些问题是如此明显和让人讨厌…我将使用这篇文章作为我们系统分析师的简易指南。请在评论下方自由分享您在需求文档方面的经验。
Translated by ChatGPT gpt-3.5-turbo/42 on 2023-12-16 at 16:00
