会写需求和懂写需求的区别

Posted 2020-09-30 氢氦

 

注：本人为ABAP技术顾问，故以SAP实施过程中的功能说明书（Function spec，以下简称FS）的编写为例，说说我关于FS写作的一些看法。

       在SAP领域，写FS的人很多，会编程的也不少，但真心懂写作，懂功能说明书的人却不多。很多人扮演着ERP实施顾问的角色，只是单纯为了完成工作而写文档。只要能够实现功能，哪怕里面埋了很多雷挖了很多坑也无关紧要，甚至FS本身就是形式的存在，以至于难以依据它得知任何有关功能的真正情况。SAP系统最注重的是功能的完整性和严谨性，因为一旦程序有问题，影响的并不只是程序本身，更会影响到实际企业生产，甚至一定程度上影响到决策层的判断。跟SAP的开发一样，在功能说明书的编写方面，没个大几年的累积经验是无法成为大神级别的；除非之前就有相似的工作经验，并认真训练过自己。因此能发出功能说明书并没有什么了不起，跟其他诸如测试、开发工作一样，培训一段时间就能够上手了，但真的要做到把控需求，精确的定义功能，写出逻辑清楚、行文流畅、可维护的功能说明书，可就不容易了。也印证了一句话：会写FS的不稀奇，懂写FS才难求；会操作业务模块的人不稀奇，即会业务又能写作的才万金难求！

       以下列举几项，简要说说会写FS和懂写FS的区别：

 

（本文参考了一位园友的文章：会开发和懂开发的区别。本文以娱乐内容为主，如有雷同，纯属故意）

主体与客体

谁在写？为谁而写？这个问题的答案将决定文档的写作形式和写入内容。

在文档的编写过程中，这是一个十分基础的问题。本文中的FS，指的是在SAP系统实现阶段阶段的一种文档，它是由SAP业务顾问写出的、面向开发人员的文档。它不是业务蓝图、不是配置文档，也不是培训文档。

一些业务顾问，对需求的认识是清楚的，但是却搞不清自己写作时的主体和面向的对象是谁。所以行文飘忽，内容冗杂，重点不突出。

长句与短句

在写作过程中，句子有长有短，这是理所当然的事情。因为简单的事情自然可以用简单的语言描述，复杂的事情则会不可避免地将语言推向复杂...

复杂的长句，通常会有着较高的理解成本（想想英国大臣吉姆·哈克面临过的窘境），写作者应该尽量避免它的出现。这就要求写作者有以下才能：

1. 精确地把功能本身抽象出来，而不是其他的东西。
2. 掌握一点点写作技巧，学会把话题划分为若干个子话题。　　

其中，1保证了读者不会收到无关信息的干扰；2则通过一定的冗余提高了文档的可读性。举个例子，我要告诉读者，存在一个A，它的意义等于B+C+D+E+F+G+H。读者在看到这句话的时候一定会思考，这七个字母到底代表什么东西？就算他知道了答案，也往往需要把它们全部背诵下来，才能顺利地进行阅读。而聪明的写作者也许会从X = B + C谈起，增加几个式子，却让它们的单个长度缩短，以适应人的思考能力。

书面语与口语

短句不能等于口语。尽管写作者应当尽量使用短句，文档自身的性质依然要求他不能忽视书面语的运用。相对于口语，书面语有着更加通用、更加持久、不易出现歧义等优点..对于FS来说，这些都是重要的特性，需要通过书面语来予以满足。

也许读者会觉得这种要求是不言自明的。遗憾的是，的确有部分业务顾问在尚未习得书面语的情况下，就开始了自己的职业生涯。 

版本控制

和程序一样，对FS而言版本控制是不可缺少的存在。文档的修改必须通过版本加以区分，不然无以追溯信息的变化。这还有一个前提是功能本身的修改可以通过文档来反映。一些业务顾问喜欢用口述的方式向开发人员交代自己的新想法。一段时间过去，经过若干这样的修改，新人们会发现自己能看到的FS和实际的功能完全是两样东西，从文档中得不到任何参考。过去的事情成为了空白的历史，功能成为了模糊不清的盒子。这是很糟糕的局面。为长远计，更新文档的意识对业务顾问是必要的（题外话：对程序员而言，技术文档也是一样的道理）。

还有一些人不知道word有一个很好用的“审阅”功能，通过它，文档可以很清楚地记录文档修改的内容、时间、修改人等历史信息，并可以让其他读者通过打开相关标记的方式来方便地获取它们。如果使用手工的方式维护这些信息，既繁琐又容易出错。

 此外，有的业务顾问喜欢用“增量更新”的方式来更新需求：不是在原有的文档上更新，而是一次次地发布小的“变更文档”来更新。这种做法在某些情况下是有道理的。然而作者必须警惕它带来的几种风险。首先，增量更新会给后人带来相当的理解压力。因为他要搞清楚一个需求的现状，很可能不得不将N份更新文档从头读到尾。另一个问题是，甚至连FS的作者本人也有可能因为更新的增多而失去修改的基准，从而生产出不一致的内容，这种情况毫无疑问是危险的。

DRY

不要重复你自己（Don\'t Repeat Yourself）。一些业务顾问喜欢把自己写的大段文字进行复制，粘贴到各处去，这样做是不对的。

就和编程中要谨慎对待复制粘贴代码一样，写作FS时也要尽量避免这种做法。实际上，如果一个业务顾问能做到对版本的合理控制，那他会自然地意识到复制粘贴的弊端之一：如果把同一段文字复制到多处，那要修改这段文字的内容的时候，可就有大麻烦了..好的文档就和好的程序一样，要经过反复的抽象提炼之后才能产生。

用代码代替功能说明

首先，在FS中写入SQL和伪代码是常见的做法，这在多数情况下时合理的，因为程序语言在逻辑表达方面有着显然的优势。

但逻辑表达不是一份FS的全部，一些业务顾问，为了和开发人员表示亲近，或者为了炫耀自身的编程知识，往往会在文档中写入过量的SQL和伪代码。在某些情况下，甚至除了代码之外，什么都没有。这种做法的问题在于，FS的基础是功能的描述，并不是功能的实际实现。此外，用代码来描述代码，也会陷入表达的死循环。就算是技术文档，使用这样的写法来写作，也是不合格的。

 

以上几节列举了我在开发经历中所遇到的FS存在的问题。还有很多很多实际存在的不良文档，都是那些只知道写文档而不懂写作的萌新写的。比如基本的排版、比如错别字漏字、从来不懂什么叫word审阅。遇到这样的事故，有时候会哭笑不得，要给IT增加不少的负担。也只能感叹一句，操作系统简单，懂写作难，懂业务又能写作，简直万金难求！

 

本文链接：http://www.cnblogs.com/hhelibeb/p/7247909.html