Fork me on GitHub

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

 

注:本人为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

posted @ 2017-07-30 04:29  氢氦  阅读(2035)  评论(0编辑  收藏  举报