[翻译]无痛功能规格说明书——Part4：提示
我们已经讨论过了 为什么您需要规格说明，规格说明中应该有什么，以及 谁负责编写规格说明。在本系列的第四章也是最终章，我将要分享一些关于编写规格说明的建议。
在一个经常编写规格说明的团队中，您常常能听到最大抱怨是“压根没人去读他们”，如果规格说明真的没人读，那么负责编写规格说明的人难免会变得愤世嫉俗。这就像一个经典的 Dilbert 漫画，里面工程师们用厚达 4 英寸的规格说明文档堆砌成隔板来扩展他们的工作隔间。在典型的大公司里，每个人都要花上好几个月的时间来撰写枯燥乏味的规格说明。一旦规格说明完成，他就会被束之高阁，再也不会被翻阅，最终产品会从头开始开发，完全不顾及规格说明的内容，因为根本没人会去读他，因为他实在让人昏昏欲睡。撰写规格说明的过程本身可能是一项有益的练习，因为他迫使每个人至少都去思考相关的问题。但问题在于，当规格说明完成后，他失去了作用（无人阅读，无人喜爱），这会让人觉得所有付出的努力都白费了。
另外，如果您的规格说明从未被仔细阅读，那么最终产品交付时就会带来很多争论。 某个人（可能是管理层、营销人员或客户）会说：“等等！你答应过我会有一个蛤蜊蒸锅功能！蛤蜊蒸锅呢？” 程序员则会回应：“不，实际上，如果你查看规格说明的第 3 章、第 4 小节、第 2.3.0.1 段，你会发现他明确写着‘没有蛤蜊蒸锅’。” 但这并不能让客户满意，因为“顾客永远是对的”，所以脾气暴躁的程序员不得不回去给产品强行添加一个蛤蜊蒸锅功能（这让他们更加愤世嫉俗地看待规格说明）。同样的情况也可能发生在管理层身上。例如，一位经理可能会说：“所有对话框里的文字都太冗长了，每个对话框顶部都应该放一个广告。” 然后沮丧的程序员会辩解道：“但是你批准了规格说明，里面精确地列出了每个对话框的布局和内容！” 然而，经理当然没有真正读过规格说明，因为在他尝试阅读时，他大脑里的内容满的都快要从眼眶里渗出来，而且这还影响了他周二的打高尔夫球计划。
综上所述，规格说明书是好东西，但是如果没人阅读他就毫无作用。作为一名规格说明的编写者，您必须引诱别人来阅读您的作品，您还必须小心谨慎，不要向别人小小的脑袋里塞太多东西，避免那些东西从他们的眼眶里渗出来。
引诱别人来阅读您的作品意味着您需要写出好作品，但是如果我只是撂下一句“要成为一个好作者”那显然有些不公。这里有四条规则，您 必须 要遵守，这样才能写出容易被人阅读的规格说明书。
规则一：有趣
引诱别人来阅读您的规格说明的第一条规则就是要让阅读体验变得有趣，别跟我说什么您天生无聊，我不买这个帐。每个人在每个时刻都有一些有趣的想法，他们只是自我审查一番之后觉得这些东西“上不得台面”，emmm，有时您必须打破规则。
如果您阅读过我在本站上写的 volumes of garbage，您就会发现我零星散落着一些各种搞笑的尝试，就在几段话前我还在调侃管理人员的脑容量和他们打高尔夫的事情。即使我不是真的很有趣，我也在努力的去尝试，而且这种笨拙的搞笑尝试本身也会让别人觉得好笑，就像是悲伤的小丑一样。当您编写规格说明时，一个很容易逗笑读者的地方是示例部分。每当您需要通过一个故事来阐述某种功能原理时，不要这样：
- 用户输入 Ctrl+N 以创建新的雇员表，并开始输入雇员名称。
而是应该这样：
- 佩奇小姐用眼线笔戳着键盘，因为她胖乎乎的小手指太胖了，无法按单个按键，她键入 Ctrl+N 创建一个新的男友表，并键入单个记录“Kermit”。
如果您曾大量阅读过 Dave Barry，您会发现有一种简单的搞笑方式就是在不必要的情况下加入大量具体的细节。“精力充沛的哈巴狗”比“狗”更有趣、“佩奇小姐”比“用户”更有趣，与其说“利益相关方”，不如说“左撇子的鳄梨农夫”，与其说“那些拒绝清理狗屎的人应该收到惩罚”，不如说他们应该被“关进那种孤独到让他们想上自己的狗的监狱”。
哦，对了，如果您认为加入幽默元素显得不够专业，那很遗憾，只能说您没有幽默感。（别否认了，没有幽默感的人总是会否认，你骗不了我。）如果您所在的公司因为您的规格说明轻松有趣、易于阅读而降低了对您的尊重，那么就去 找另一家公司 吧，因为人生苦短，实在没必要在如此严肃悲惨的环境里浪费宝贵的时间。
规则二：编写规格说明就像是编写大脑可执行的代码
这就是我觉得程序员在编写规格说明的路上可能遇到的阻碍。
当您编写 代码 时，您的受众是 编译器，是的，我知道别人也可以去读代码，但是这 对他们来说很难。对于大部分程序员来说编写能够被编译器正确阅读和解释的代码已经足够难了，而编写人类能够阅读的代码更是成了一种奢求。无论是您编写：
void print_count( FILE* a, char * b, int c ){
fprintf(a, “there are %d %s\n”, c, b);}
main(){ int n; n =
10; print_count(stdout, “employees”, n) /* code
deliberately obfuscated */ }还是
printf(“there are 10 employees\n”);您得到的输出都是 相同的，这就是为什么，如果您仔细想想，您会发现程序员往往会写出这种东西：
假设函数 AddressOf(x) 定义为基于 RFC-822 说明的合法的 ANSI 字符串邮箱地址对用户 x 的映射。假设有用户 A 和用户 B，当用户 A 想要发送邮件给用户 B 时，A 初始化一个新的消息（使用别处定义的，但并非使用全部的技术），之后将 AddressOf(B) 输入至 To: 编辑框。
这段话也可以这样写：
佩奇小姐想要去吃午饭了，因此她创建了一封新邮件并将 Kermit 的邮箱地址输入到 To: 中。
技术旁注：邮箱地址必须符合 RFC-822 规范。
理论上，他们都“表达”相同的一件事，但是第一个例子您必须仔细 解码 后才能理解，而第二个例子则非常容易理解。程序员往往喜欢把规格说明写得像学术论文。他们总是觉得一份“正确”的规格说明必须做到“技术上”正确，这样他们就精准的完成了自己的工作（也无需承担更多责任）。
这里的关键在于当您编写一个规格说明时，除了要保持正确之外，还必须 能够被理解，用程序员的术语来说的话，意思是规范必须被编写的能够被人脑“编译”。电脑和人脑的最大区别之一就是电脑会坐在那里静静的等待您进行各种各样的预定义，而除非您激发了读者的兴趣，否则人脑根本不会知道您在说啥。人们压根不想进行任何解码理解，他们只想要按顺序阅读下去并且理解全部事情。对于人类来说，您必须先和他们描绘一幅模糊的总体图景之后再填充细节，而对于电脑程序来说，您可以让代码从头一直执行到底，细节内容出现在他们需要的地方。电脑不会在意您的变量名是否具有含义，而人脑则更适合通过故事来理解一幅生动的图景，即便是一个故事的片段，因为我们的大脑已经进化到了可以理解故事的程度。
如果您摆出一副实战中局的棋盘，一位经验丰富的棋手只需要花一两秒钟就可以记住每个棋子的位置。但是如果您将几个棋子移动到了正常情况下他们不会出现的位置（例如，把一些兵放在第一行，或者将两个黑象都放在黑格中），对于棋手来说记忆这个棋盘就变得困难了很多很多，这就是人脑和电脑思维方式的差别，对于记录棋盘的电脑程序来说，棋子的位置合理与否与他的记忆功能毫无关系。人脑的工作方式不是随机存取的，在面对常见的情况时，我们的大脑通路会得到加强，理解事情的能力也会变强。
因此，编写规格说明时，请尝试想象您的目标读者是谁，并设身处地思考他们理解每个步骤需要哪些信息。逐句审视，扪心自问读者是否能深刻理解该句子，以及它和您之前所述内容之间的关联。如果目标受众中的一部分人不知道什么是 RFC-822，那么您既可以定义它，或者至少将它放在技术注释中，这样管理层在阅读规格说明时，就算遇到生僻的技术术语也不会放弃继续阅读。
规则三：尽可能地简单
不要由于您认为使用简单的句子写作显得不够专业而刻意的使用呆板、正式的语言，您要尽可能的使用简单的语言。
有些人使用“功能规格说明书”这种词汇是因为他们觉得“功能文档”看起来不专业。（这里又一次提及到了词汇“不专业”，任何时候当有人告诉您不应该做某事只是因为他“看起来不专业”时，您就应该知道他们已经找到不到您事实上的缺陷了）。事实上我观察发现很多人觉得把文档写的简单易读就意味着有问题。
把事情分解成短句，如果一句话解释不清楚，就用两三句话。
避免文本墙（整页都是文字），读者会被你吓到然后“太长不看”。您上次在时尚杂志或者新闻报纸上看到整页都是文本是多久以前的事了？杂志甚至会从文章中引用并以巨大的字体打印在页面中间，只是为了避免出现整页文本。使用编号或项目符号列表、图片、图表、表格和大量空白，使阅读“看起来”更蓬松。
“杂志甚至会从文章中引用并以巨大的字体打印在页面中间，只是为了避免出现整页文本。”
没有什么比大量的截屏更能提升规格说明的可读性，一图胜千言。任何为 Windows 上运行的软件编写规格说明的人都应该买一份 Visual Basic，学习如何使用他 至少 能用来表达原型设计，（对于 Mac 电脑，可以使用 REAL Basic；对于 Web 页面，可以使用 Front Page 或者 Dreamweaver），之后截图并把图片放在您的文档中。
规则四：多次校对
emmm，好吧，我本来打算在这里对这个规则进行长篇大论的描述，但是这个规则实在是太简单了，多校对几次，就这样就行。当您觉得某句话难以理解时，就把他改写的简单一些。
规则四实在太简单了，我打算加一个规则五。
规则五：有害的模板
要拒绝制作一个标准规格说明模板的诱惑，一开始您可能只是觉得让“每个规格说明都具有相同的格式”这很重要，但事实上：不要。但为什么不应如此呢？您家书架上的每本书看起来是否相同呢？您是否想让他们看起来相同呢？
更糟糕的是，一旦您拥有了模板，您就会开始有一些每个功能点都需要填写的“必备章节”。例如：Bill 老大规定，从现在开始，每个 Microsquish 产品都应该有互联网组件，因此现在规格说明书模板被添加了被称为“互联网组件”的章节，任何时候只要有人在编写规格说明，不管是否相关，他都必须填写这个被称为“互联网组件”的章节，即使他所写的规格说明只是用来描述 Microsquish 键盘。（您开始疑惑为什么那些无用的互联网商城按钮像蘑菇一样开始在键盘上疯长）。
随着这种章节的累计，模板会变得越发庞大。（这里有一个非常非常坏的规格说明书的 例子，老天，谁需要带着参考书看规范？或者说带着词汇表？）这种大模板带来的麻烦之一就是会吓跑那些需要写规格说明的人，这份工作看起来实在是太可怕了。
归根结底，规格说明就是一份您希望别人去阅读的文档，他和《纽约客》上的散文或者大学里的论文没什么本质上区别。您是否听说过大学教授为学生发放论文模板？您是否听说过两篇优秀的散文能套入同一个模板？放弃这种念头吧。