[翻译]无痛功能规格说明书——Part2：什么是规格说明书？

原文 Painless Functional Specifications – Part 2: What’s a Spec?

(您是否已经阅读了 Part1？如果没有，请点击这里。)

这一系列文章探讨的内容是 功能规格说明书，而非 技术规格说明书，人们总是混淆这两个概念。我不太清楚是否有标准化术语，但是当我提到这两个词时，意思分别是：

功能规格说明书 描述了在用户视角中的产品如何工作，他并不在意具体实现方式。他讨论的是产品功能，他决定了屏幕上的显示内容、菜单内容、弹窗，等等这些。
技术规格说明书 描述了程序内部的实现，他讨论的是数据结构、关系型数据库模型、编程语言和框架的选择、算法，等等这些。

当您设计一个产品时，无论他是内部的还是对外的，最要紧的事情就是锁定用户体验：屏幕上显示的是什么、用户可以如何使用、用户用产品做什么，随后，您开始考虑无处不在的弹窗和组件细节。在您完全决定这些内容之前根本不需要考虑使用什么编程语言，在这一系列文章中，我只讨论这一部分，也就是 功能规格说明书。

我写了一个简短的功能规格说明书示例，用来给您演示。在我们进行下一步之前，请阅读示例。（示例中的流程图）

您已经阅读了吗？

您还没读吧=。=，去读完示例再回来，这样我们才能去聊一个好的规格说明应该包含什么或者不包含什么。我会在这里等着你的，感谢。

（耐心等待中…）

啊，太好了，您回来了。

以下是一些我在每个规格说明书中都惯例添加的内容。

免责申明纯粹的自我保护作用，如果您写了一段类似于“这个规格说明书尚未完整”，人们才不会冲进你的办公室咬你的头。随着时间的推移，当规格说明逐渐完整的时候，您可以将其改为“按照我目前的了解，该规格说明书已经完成，但如果我遗漏了任何事情，请联系我。”，这也提醒了我，每一个规格说明书都需要：

有且只有一个作者有些公司觉得文档应该由一个团队完成，但是如果您尝试过集体写作，您就应该知道这事有多操蛋。把集体写作这个活留给那些拥有大批哈佛应届生军团的管理咨询公司吧，他们需要做大量忙碌的工作来证明他们的收费是合理的，而您的规格说明只需要 一个人 负责编写，如果您有一个大项目，那就把他拆成小块，每一块由一个人负责编写规格说明。还有些公司觉得让某一个人在规格说明上署名是一种“自负”或者说“窃取了团队的荣誉”，废话，对某件事 负责任 的人理所当然的拥有对这件事的 处置权。如果规格说明中的有些内容写错了，就必须有一个该规格说明的拥有者，一个把自己名字写在规格说明上的人，负责去修复他。

应用场景当您在设计产品时，您需要在脑海中设想一些人们在现实生活中使用您产品的场景。否则您最终只会设计出对现实世界没有任何作用的产品（例如 Cue?Cat）。考虑您的产品受众，为您产品的每种类型用户假设一个虚构的、完全基于想象的刻板印象。在我的 UI 设计书（免费在线阅读）的第九章谈到了如何创建虚构的用户和场景。将这些基于想象的用户带入您的场景，场景越生动具体，您为用户设计的细节就会越好，这就是为什么我倾向于设置大量虚拟细节。

非目标当您与一个团队一起开发产品时，每个人都倾向于往里塞一些他们最钟爱的、赖以生存的、真实的或者基于想象的宠物功能，如果您接受了所有这些功能，您的产品开发只会需求无限的工期和无限的金钱。您必须立刻开始剔除这些功能，而做这件事最好的方法就是在规格说明中添加“非目标”章节，明确的表示不打算做的事。非目标可以用来表达您不计划实现的功能（“不支持脑电波交互！”）或者更常规的（“我们不在乎这个版本的性能。这个产品运行的很慢，但是只要能用就行。如果我们有时间开发 2.0，我们会找机会修一下。”）这些非目标的内容可能会引起一些争议，但是重要的是赶快明确并公开。“我们没打算做这个！”就像 George Sr. 说过的。

总览这就像您规格说明中的内容目录，可以是一个简单的流程图，也可以是一个架构的细致讨论。每个人都会阅读总览部分来了解整体架构，然后再去阅读细节部分才会更容易理解。

细节，细节，还有细节最终，您开始处理细节，在需要了解某些具体的细节实现前，大部分读者不会仔细的阅读这些内容。当您在设计一个基于 web 的服务时，一个很好的做法是给每一个页面分配一个规范的名称，并使用一个单独的章节来描述这个页面中所有令人麻木的细节。

细节是规格说明书中最重要的内容。您应该已经注意到了在示范的规格说明书中我如何使用 令人发指的 详细方式来描述登录中的错误处理。当 email 地址不合法时如何处理？当密码不正确时如何处理？所有这些情况都对应着后续实施中真的需要编写的代码，而且，更重要的是，这些情况对应着事情该怎么做的决定。总有人需要负责决定当用户忘记密码以后该如何处理，如果没有决定，代码就无法编写，规格说明的职责之一就是记录这些决定。

开放讨论在初版规格说明放置开放讨论是完全没有问题的，当我编写第一版的草稿时，我通常会放置大量开放问题，但我会标记他们（使用某种特殊的格式以便我后期检索），而且如果合适的话，我会加一些自己的建议方案。在程序员开始工作之前，所有这些开放讨论都必须被拍板。（您可能觉得可以让程序员先从简单、已经明确的部分开始施工，随后您再去解决剩下的开放问题，但这其实是个蠢主意，因为除了那些您事先已经了解到而且应该解决的问题外，随着代码实现工作的开始，您还会遇到无数个新的需要解决的问题。另外，您对任何问题解决方式的决议都有可能对代码的设计和编写产生影响）。

旁注当您在编写规格说明时，请记住您的读者群体是多样化的：程序员、测试员、市场同事、文档哥等等。在您编写规格说明时，您可能会想到一些只对其中某一组人有用的内容。例如，我通常把写个程序员的一些关于技术实现细节的探讨标记为 “技术旁注”，这样市场方向的同事就会忽略这些内容，而程序员则会阅读他们。我的规格说明中常常充满了类似于 “测试旁注”，“市场旁注” 或者 “文档旁注” 之类的内容。

规格说明是活的有些编程队伍采用“瀑布式”流程：一次性搞定程序设计，编写规范，打印出来，扔给程序员然后下班回家。对于这种团队我想说：“呵呵”。

这种工作方式就是规格说明书声名不好的原因。有很多人这样对我说过：“规格说明书没啥用，因为根本没有人会去遵守，他们最后总是过时的，根本无法反映出产品。”

抱歉啊，也许您的规格说明书过时了，而且没法反应产品情况。但是我的规格说明书可是更新的十分频繁。我的规格说明书随着产品的开发进度和新的决策不断更新，我的规格说明书随时可以反映团队对于产品方向的最佳共识，只有当产品代码已经完成时（所有功能开发完成，仍然遗留有测试和 debug 工作）他才会被冻结。

为了让大家活的轻松点，我不会每天更新规格说明。我常常是在服务器上保持一个最新的版本，以便团队可以将其视作引用的参考。在偶尔的里程碑中，我会打印一份带有修订标记的规范副本，这样人们就不必重新阅读整个内容——他们可以扫描修订标记以查看进行了哪些更改。