研发文档管理体系建设

研发管理沙龙

——研发文档管理体系建设

时间：2003年12月10日（周三）下午2：30～5：10

地点：明华国际会议中心 (汉华深圳总部)

主题：研发文档管理体系建设

主持人：朱光辉（汉华公司研发管理培训&咨询部总监）

组织策划：周志强(汉华《研发管理》刊物编辑部主任)

邀请嘉宾： 张绥平（南太电子）； 黄亚平（吉大远望软件）；

熊磊（好易通公司)；王欢（UT斯达康）；刘琳(国微电子)；

内容：

　　十二月十日，来自UT斯达康、南太电子、吉大远望、好易通、国微电子等公司的相关研发负责人，与汉华的资深顾问们齐聚于蛇口湾畔的明华国际会议中心，参加由汉华企业管理咨询有限公司举办的《研发管理》沙龙系列活动。

　　本次沙龙的主题是：“研发文档管理体系的建设”。沙龙上的气氛轻松而活跃，与会者纷纷各抒己见。交流了文档建设过程中的问题和困难, 分析了困难产生的原因, 以及提出了一些有效的解决方法。 包括文档体系应该包含哪些内容, 如何建立文档体系, 以及如何推行和有效的实施文档管理, 即如何有效的与绩效考核相结合的问题, 与会者分享了各个公司的经验和教训。汉华顾问结合与会者提出的问题，也发表了一些建设性的意见和建议。会议结束后，大家都觉得收获很大。汉华组织的这种形式的沙龙给主管研发的经理们提供了一个非常好的交流平台，大家都受益匪浅。

　　以下记录内容中均以姓代替人名。

　　由于内容比较多，本刊将分两期发表。本期发表第一部分，第二部分详见下期。

　　在各位嘉宾简单自我介绍之后,沙龙正式开始。

　　朱：(汉华资深顾问)我们这个沙龙不是培训，所以我们随意一些。

　　文档建设这个工作是非常难做的，我以前在华为当了三年的项目经理之后，把我调任了一个新的职务, 叫文档管理员. 于是我的文档工作就管了一年，所以我待会可以跟大家交流一下文档管理的经验和教训。

　　今天大家发言围绕几个主题，第一就是文档建设过程中遇到过哪些困难. 举个例子，比如说文档不齐套,一些文档是错误的，常常跟我们具体内容对不上. 以前我跟一些项目经理聊天，这些项目经理就跟我开玩笑说，最好让竞争对手把我们的文档都偷去更好,为什么呢?我们的文档错得一塌糊涂,偷去准把他们搞死；第二是为什么会出现这种问题，我们要分析为什么会出现这种问题的原因，不知道这个问题发生的原因我们就不能从根上来解决这个问题；第三，就是怎么解决. 每个在座的都可以谈一下经验和教训。

　　熊 我先抛砖引玉。

　　我们公司对刚刚朱老师的问题深有感触。文档不齐，文档不对深深困扰我们的文档工作. 文档不齐主要是工程师很忙，每一次都推托。“哎呀，这次这个文档我先不做了，我下次一定补上”。这一次就漏了，慢慢积累下来就什么文件都有缺的。有文档但就是都缺。文档不对的问题就更加严重了，每一次新发一份资料都没有更新，我记录了一下我们公司文档至少有两百多份吧，从来没有更新过资料，那资料就肯定全是错的，错的一塌糊涂。

　　然后解决问题我们现在是这样考虑的，我们准备从纸件和电子件两方面考虑，于是就引用了Notes. 现在还是比较有成效. 我们建立了一些电子流，比如说一些文档传递的电子流，文档必须更新了以后才能往下走. 然后建立了一个公用的电子库一样的，就是每一次图纸都要往里面存，才能往下面走，但是因为现在是建立初期，还是有很多不完善的地方: 怎么去维护? 怎样去保证文档的齐全, 还是没有一个根本的办法，不能从制度上来保证。

　　张：你们有没有一个关于研发文件的管理体系? 先不说整个公司的文件，像刚才朱老师讲整个的体系建设。因为首先决定你要出什么文档，然后才能谈你管什么文档. 就一个Project而言，从开始到Project的结束，你们现在有没有一个文件说明哪些文件必须出，在什么阶段出？在一个project 开发的过程中会有很多文档。有的是受控的,有的是不受控的. 受控的话一般很多，就相对来讲比较简单一些. 比如一些牵扯到公司最重要的物料啊，设计变更啊，这肯定会受控，用note 管理的一般是受控的文件。但实际上研发中很多重要的文件,比如和生产或物料等其他部门牵扯问题不是很多的时候，就不受控了。实际上这部分文件对Project来讲，对以后的产品开发来讲也是很重要的. 那么你们有没有一个体系，就比如说文件编码吧. 因为你文件的目的就是怎样最快的把它检索到，要检索的话，首先要有编码，和物料编码一样，文件也要有编码，你们有没有一个规定，或者说管理体系,规定什么文件采用什么编码?

　　熊：这个是有的。就是我们有专门文件编码的业务指导书，我们在前年做ISO9001的时候就已经建立了这个文件，就是规定应该有哪些文件，比如说一立项就应该有预研报告、产品设计规格书、市场调研报告等这些东西。

　　指导我们工作的最大的有三个流程：一个是开发设计流程；一个是变更流程；还有一个就是怎么量产，量产移管程序。这三个的话，要输出很多文件. 这些文件我们也有一个专门的体系. 在三个大的文件下面，我们又分了上百个业务指导书。比如说文档应包含哪一些项. 比如每次开会邀请哪些人等这都是固定的，第一个是在什么时间要开哪些会，每个会要准备哪些文件，要输出哪些文件这些都是有规定的

　　至于文件编码方面我们也比较简单，比如说SYPN我们的标志然后杠1l, 杠rb是我们研发,然后杠后面就很简单了. 比如说03001,零三年的第一份 。不按Project分，就是任何一个Model都可以. 就是说从开发部发出的文件都是RD-03001为顺序的.

　　张：通过部门文员往其他部门发的文件，大部分公司也都会这样登记。因为文员最基本的发出去文件他要登记编号。但在Project里不见得所有的文件都通过文员往外发.

　　熊：我们现在基本上不容许文件私地下给别人，全部都是文员给，全部通过一个接口. 我要找什么文件的时候大概一输就可以找出来

　　张：你是电子登记，就是在Excel里列个表，把他打进去，然后把文件名也打进去，或者是还有编码也打进去，那这样如果我要找某一个Project 文件的话怎么找

　　熊：检索，按关键字来找。但我们下面一步就想做一个公用的平台，分Project，每个项目组分给他一个区，但都是保密文档，这个区的密码由每一个项目经理管，但这个电脑的开机密码比如说由我管，所以说他独自拿不到这个文件，然后我也拿不到这个文件，因为我不知道各区的密码，而办公室的钥匙则由我们主管拿着。

　　张： 你的File没有按Project区分，你这个Project完成的时候又要结束这个Model，结束Model时你要去先看文档,象你这样你是不同的Projece在一起，你怎么去Check这个项目小组，怎么看这个文件有没有完成？一个Project 完成以后怎么保证每一个文档都是最Update?

熊：是这样的，在项目完成的时候,包括结构性图纸、电子原理图啊, 这些全部要交到公司的文档中心去管理，交一份整套的过去，起一个管理的职能. 这时文员每一次复印的时候会多复印一份，另外装订成册，按Project 这种形式装订成册，然后他每一次零一版产生后，就会把零零版作废或盖作废章。

　　这样一般到最后都会有欠的文档，到最后就催他们赶快补齐，列个清单给他们，因为我们每回最后一次小批量生产的时候公司的文档中心都要签字的，要给项目组打分，文档不全就不签字，逼迫他们补文件，补到文档中心满意为止。 就是说在小批量生产之前有一个评审，在这个时候督促他们补齐，不补齐的话就不能转量产。

　　张：因为你是做对讲机的，肯定也是系列产品或者是新产品，实际上在一些核心的东西上基本上是共用的，这样你的文件更显得重要，因为你的一个新的Project Team 开发一个新产品，可能只是在某一个原来的Model的基础上修改了一些东西，那你怎么去节省时间呢，你要把原来的文档要拿出来看。

　　熊：我们现在就是分了很多柜子，每一层一个系列，每一个机型是一层，但一个机型里分很多系列机型。

　　张：但你一个系列机型按这个流水号的话等于你的号在跳，你看不出来全还是不全。假如说这个Project 从001开始，先不管它是不是update……

　　熊：但这之后你应该是有Bom的，对着Bom清单你就知道全不全。就是说从你的文件里面专门对每个Project,然后把他挑出来形成一个List . 你每一个机型，不管什么机型，就算是同一类型机型都会有一个Bom的，我指物料单.

　　张：从物料单只能check针对不同Part 的图纸文档及相关part的spec.但还有开发文档，最大的问题是在研发过程中的过程文档。如概要设计报告,详细设计报告. 概要设计报告这些东西，你不交的话可能5年都没事。

　　熊：这正是我们部门的工作，我们部门会有一个清单，不管它是什么机型，他都要交这些东西，比如一页报告，你可以很简单，见xxx文档，如果是新立项的话会写的很厚一本，如果是客户要求的那就会见合同等，我们每一个机型都会有从开始预研报告、设计开发手册、到后来要输出什么文档，就会有一个清单出来. 我们文员就拿着这个文档清单去查看. 他不管文档的具体质量，因为质量最后要由其他专业人员来评审的，所以说做得不好也是有的，质量问题通过评审就可以看得到的，比如说模具费开模等多少钱呀,等不可能都写见xx，最后还是会写一下。这样工程师还是会老老实实写出来的。

　　张：我觉得你们这个考虑文档已经考虑的很多了，假如说到最后这个Project 完成的时候你都可以有个List，那你们这些文档有没有一个模版？因为你没有模版的话有些人可能做三行，有些人可能做三页。

　　熊：以前我们没有模版。规定相关的内容都要有，但模版可以发挥。现在就想做成模板式的，但由我来做了一个模板之后，大家都说不好用。

　　朱：那是自然，做得再好都会说不好用，模版要工程师去做，让他们自己做他们不会说不好用的。工程师觉得模板不好用,但他又拿不出一个更好用的模板来，而且他说的都是客观存在的理由，举例告诉你这里为什么不好用。

　　熊：但模板是可以慢慢的改，先做个初步的出来。我们会在成型文件里会说预研报告要包括市场调研、市场分析等。

　　张：在一个Project 开发的过程中，有没有一个单独的文件，规定在什么阶段出什么文件。就是说在这个Project一开始就已经规定了在什么时间出什么文件，因为不同的Project 是不一样的。

　　熊：有。而且这些文件都要评审的。我们一开始就会有几张纸出来，列出哪些是要评审的，这个(资料)就交给项目组，给他们看. 你要经过这些，然后输出什么文档，最后就是文员在那里打勾，相当于一个Check List ，然后可能会增加一些评审点，那就在后面加。后来会发现评审多了一些,比如客户突然有什么反馈呀,就是说固定的评审他必须做。

　　张：真正要把一个Project文件搞齐的话，真的很麻烦。

　　熊：而且最大的问题不是有没有，而是时间上对不对的上，就是说应该是1月1日出的文件，可能到7、8月才有这个文件。明天又是内审，那个内审员最清楚我们的问题就是时间对不对的上，每次文件都有，但是一看：预研评审是在1月1日，为什么你这个文档还在7月还在填。这就类似于用ISO来检查前伪造文档.

　　刘：我想问一下，现在有一些文档管理的软件，里面也反映了基线. 版本反映在软件里面了，而且实时可以去提供的，是根据服务器网络来，大家有没有考虑用这种软件。

　　前段时间北大青鸟到我们公司来推荐软件，当时一个是经费价格的问题，另一个问题就是他向我做介绍的时候，也说了一些象我们这样的公司在用他们的软件，还给出了某一个项目里面的具体的文档，还后对我说这是比较机密的资料，具体内容不能让我看，但还是有一些具体的内容出来了，我在想，因为这都是和服务器挂上的，会不会在这些软件里边会有后门，会不会我们在用这些软件的时候他就已经知道我们的技术资料了。

　　黄：那要看你的网。比如政府的内网和外网是彻底隔离的。就是物理隔离。

　　张：基于web的话是很方便的，但安全是一个问题，我们现在已有一个客户在用基于oracle和metaphase而开发的系统，我们现在要进入这个系统要四个code，一个username ，一个password还有一个pincode, 还有一个number，这个随机number专门有一个生码器生成它，在我把Pincode 输完后再输入这个随机码。生成哪个码就是这个码。

　　黄：我们给客户的都用活体指纹。

　　熊：我们就用钥匙,密码和人分离的方法.

　　张：你要基于Web的话，和你的供应商、和你的客户沟通之间不存在问题，假如说你今天在深圳，明天到上海去了，你照样不影响你的工作，只要带个笔记本电脑，上网就行了。不论走到任何地方，你和你的客户用的是同一个平台。

　　黄: 我们在文档建设方面也遇到大家所讲的问题.你们可能都是电子类、消费类产品，我们就是纯软件的，所以文档就更重要。

　　比如项目经理要查一些东西，如果没有文档的话，就非常难维护. 跟进过去要花半个月至一个月时间，而且我们的文档最初始的需求是这样的，根据这个需求会派生出一系列的文档来，比如概要设计、分析、详细设计、甚至用户手册这一整套的东西。因为需求是经常变更的，一般来讲，能保证需求方面的文档能达到比较新的程度，比如最近一个月. 但是对后续的，比如说分析方面就比较难了。

　　我们在日常的管理中也想了一些办法，

　　第一就是给这些研发管理人员进行培训，提高对文档的认识，因为大家都觉得我做的就是产品，我把产品做出来给客户了就OK了，文档又不能卖钱，但实际上文档在验收当中是很重要一项.

　　第二就是象一些内容能快速的对文档进行变化更新的跟进机制，比如我们自己开发的一些文档生成工具.

　　第三就是刚才大家提到的采用标准的文档格式，这有几个好处，第一写的时候有针对性，比如客户的需求，一般需求是什么，在特殊情况下有什么需求，还有这个分析基本的功能有哪些，特殊的功能有哪些，分条分块,既方便写又方便看，也方便交流。

　　第四点就是把文档提高到一个配置管理高度来讲，把它跟代码,设计文档都当作配置项, 定期的由配置管理员进行一些审核，然后对验收前等重大的也是组织评审。

熊：文档最值得借鉴的就是日本的文档。他们交过来的OEM文档真是齐整.

　　大家：老外作文档做得真不错,几乎到了傻子都能看懂的地步. 他们的文档从一份文档就可以看出经过了多少次变更,每次变更的内容.

　　黄：我们开头的第一页都是文件变更控制，什么时候由谁变更了哪一部分。但实际上这些都是空的。文件编号到3.0,4.0,我们现在都是1.01,02、03这样编，然后有重大的变更的话就取2.0,再有大的话就3.0，我们编号的规则可能跟你们不一样，我们是按项目来分的，比如说深圳市建设局……

　　而像这种游离在正规的编号之外，比如某年某月关于某重大需求的会议的会议记录，这个我们就专门搞一个目录，我们用Vsourcesafe , 主要就是当作一个文件服务器. 项目文件里包含会议记录、周报、月报等，但技术文档在不在编号里.

　　熊：我们公司和你们公司不一样，我们公司是有一个项目开发手册，其中有一栏里边专门放.置会议记录,周报,月报等，这样便于以后查找。

　　张：你的项目文档在编码系统里是怎么样编的？

　　黄：比如说测试. 包括测试反馈方面我们也专门有一套文档。这套文档是这样的，在测试的初期按照功能模块来，我们分为单元测试等.

至于文件的编号则统一的比如xx系统第一次测试，里面有很多个文件，差不多的时候就拼成一个文件，用Word或Excel。

　　张：Software你要测试的话，首先要有一个Instruction，就是说如何去测，然后根据你这个指导书再去测，相当于一个实验报告。

　　黄：原来有些项目的客户就要求我们有测试计划。测试计划里边包含测试样例,输入是什么东西,输出是什么东西等. 现在软件测试还包括很多东西,包括软件功能有没有达到, 如逻辑功能,我输入某个东西,在某一块是否输出什么东西.

　　我们以项目为主，每个项目有一个编号

　　张：那假如说想找一个几年前的项目，怎么样很快的去找到。

　　黄：就是在Vsourcesafe里的项目的目录里源代码、数据库、文档等这些方面都有。如果配置管理做好，这些问题就可以搞定。起码这些文件在逻辑上是可以找到的，在物理上可能是一个文件.

　　另外在我们配置管理里面有这种编号，就有点像顺序号，如果他是文档的话，我们就叫Doc001，就是针对项目里面的，但这些主要是用来配置管理自己看一看的

熊：这个找起来我觉得还是比较快的，每次不会超过一分钟，只要知道内容. 关键是你找到他对你有没有用。

　　张：我却觉得找文档是个问题，一个项目完成, 你至少要写300个文档. 一个公司十年就有上千个Project ，你怎样在上千个Project里，找几年以前的某一张图纸，或某一个具体的文档。

　　黄：全文检索。我们有这个软件，比如你要找建设局会议，打关键字就出来了.这个软件可以检索的文件有两种，一种存在数据库里，一种就是纯文件的光盘检索系统.我们自己都开发出了文档生成工具，更改后只要点一下，一百页,六十页的文档就自动生成出来了.

　　王：那你全文检索肯定会出来很多很多文件，你还得在其中再找，这比较麻烦

　　黄：那这个就相当于在搜索引擎上搜东西一样，你可以输入会议日期, 如果你自己也参加了,就可以打自己的名字再检索

　　王： 我们公司的文档很齐全，或者说太多了. 我们有System Requirment,然后Higtlight Design, Detail Design. 还有用户文档.

　　我们一个系统很多个网员，会写很多文档. 我们有一个文件系统叫PDS，可能是国外的，也是检索，但是会有一个文档上载人员. 你可以把文档上载上去，由他来决定他的关键字、项目、类别，然后存在数据库里，我们每个人有一个密码，我可以去搜索文档，但问题是，搜索出来的文档很多，要么找不着，找着了也不是我所需的。可能是上载人员对关键字的敏感度不好，另一方面，这个软件可能在逻辑上真的有一定的问题。

　　我们现在想的弥补办法就是做一个Project这样的网站，每个Project有一个网站,然后按网员来分。每个产品都有一个Excel文件，从里面列出了各类文档在PDS上的number ，这个相对来说就互补了一下，比较好，但就要求项目管理人员比较勤劳。因为公司已经有一个PDS在上载文档了，做不做Project网站仅仅是个人的意愿，根据自己的工作态度来做，但对于我们寻找文档来说就希望能两者相结合。

　　文档很多，该怎么有效检索的问题. 全文检索我觉得还不是很好，我们有一个软件检索的Public Document System，也是从国外引进的，我感觉还是不很理想，我们经常查找不到需要的文档.

　　黄：我们的系统，比如要查江泽民同志在xxx会议上的讲话，打入关键字就可以了, 关于这次会议的资料内容就全部出来的.

　　张：我觉得文档跟公司的重视程度有很大关系，看让谁去做。比如开发文档要让开发部的主管或Manager参与，去建立体系，不然就会面临很多问题。

　　必须是一个职位比较高的人员, 或者说他本身就做过很多文档,有切身体会，或在检索中就遇到过这类问题。比如我就有这类问题. 因为文档最基本要有编号,Version，有历史纪录，命名，怎么保存，这些全都要标准化，但建立这些所花的工作量是很大的. 而且你的目的就是检索要快，才能提高你文档的利用率，对以后的开发缩短时间。但现在我们的客户按　　Project,做得很复杂，但他们要找文档很简单。客户是这样做的，像我们做一个Bom，你的产品是分层的，你的物料在Bom里是分Level的，我的客户是这样做的…………他们的编号每个字母都代表一定的含义.他的Bom是个Part,还是其他,在他们的编码里边都可以体现出来.你看索尼爱立信手机上都是KRY开头,装成整机以后就是KRY开头了.包装盒是DPY开始,只要把码输入系统,所有的相关文档资料就出来了.

　　朱：老外的文档就是说,要看懂这个文件你需要具备哪些技能，只要具备该技能就肯定能看懂，不象我们就是个博士生你也看不懂。

　　张：因为我们写文档不考虑别人，只考虑自己, 而没有站在看报告人的立场上

　　黄：老外也投了更多的人力资源，我们中国的软件业都有点急功近利，所以能省都省了。

　　张：而且还有一个问题，假如我们做这个软件，他只考虑把这个Test System完成了，他没有Manual，尽管是在公司内部. 我们的国外客户做完一个Test System后,都会有做一个Manual, Manual告诉你怎么去做,用哪些设备.怎么去操作.我们一般会有一个Spec, 只关心test的输出是否正确..。他不关心他走了之后设备怎么连接维护，因为对这个Tesk System我们的工程师没有一个说明书. 而国外客户,尽管它是公司内部的测试系统, 它们也会做一个很详细的六七十页一百页的说明书。我们就很少有, 有的也是只有7、8页。

　　黄: 象测试计划, 国外有些是几百页的,连基本模板都有十几页.

　　张：但是我觉得基于Web的文件管理体系, 对于国外的客户非常的有效。

关于文档工具。我们以前的文档是你在电脑里做好,然后把它存进去. 现在则等于是同一个工作平台，Check In ,Check Out ,Approvel包括提示的内容, 生成Version等都是自动的. 但一个公司光投入做这些就要一个Project Team，做完了还要对人员进行培训、维护等很多问题。它不经过一年的运行很多问题都不知道。我们现在是作为客户的一个试点，发生问题就随时提出。旧系统和新系统并行，出了问题也没关系，旧系统还在用。因为旧系统也有一个user name和password，就是在网上有个平台，大家把这个存进去，但他的编码系统还是和这个编码是一样的，只不过你人为地需要把这个码输进去。