项目文档知多少（一）

    项目按时间先后顺序会分为若干个阶段，每个阶段会有大量的文档产生。如：项目前期会有《项目前景说明书》《项目建设方案》，项目需求调研阶段有《需求调研报告》《需求评审报告》，项目设计阶段有《项目开发计划》《功能特性列表》《功能规格书》《详细设计报说明》《数据库设计报告》《uml设计说明》项目开发阶段有《项目开发进度报告》《项目版本说明》《项目会议纪要》项目进入实施阶段后，相关的文档就更多了《现场实施计划》《项目安装手册》《系统管理员手册》《用户手册》《客户联系人表》《客户服务器环境配置表》《硬件签收单》《用户反馈说明》《需求变更说明》《客户培训计划》《客户培训签到表》《项目试运行申请》《现场工作备忘录》《现场人员评价表》项目验收阶段有《项目阶段验收报告》《项目整体验收报》等等这些较为常用的文档。
    一、《项目前景说明》

    个人感觉是形式大于内容。该文档主要谈的是项目背景，客户环境，预期建设目标，产生效益，都是些大而空的话，对项目开发没有实际意义。这份文档的作用仅供甲乙双方的高层领导参阅，其他的项目关系人不是看不到，而是根本就不会看。这份文档一般是由公司的管理咨询部来编制，也只有他们才能站在领导的层面上去编写非大众阅读的文档。
    二、《项目建设方案》

    这份文档大多时用在投标过程中，是用于投标的技术方案。文档根据客户在招标方案中所规定的内容来制定相对详细的建设方案〔此时由于没有经过需求调研，方案也无法过于详细。不过，我还真没见到中标之前就率队到客户现场开展需求调研的做法，客户也不允许这样干,否则容易产生误会〕。《项目建设方案》的好坏会直接影响到投标得分的高低，而且一般是由客户方的信息化的专职牵头组织，各业务部门派人配合，组成评审小组对其评审。因此方案的编写大多情况下由管理咨询顾问来编写。另外，该方案也为项目范围划定了边界，需求调研也会遵照着划定的范围开展工作，因此该文档在项目前期具有指导意义。
    注：如果项目合同附有《技术协议书》，那么《技术协议书》中所规定的项目范围多数与《项目建设方案》一致，但最终的项目范围应以《技术协议书》为准。
    三、《需求调研报告》

    这份文档是必须的。原因其一：项目接下来的设计工作都将围绕它来开展，起提纲挈领的作用。原因之二：一大帮人风风火火的在客户处热热闹闹的折腾了大半月，总得有个书面的东西向自己老板和客户的项目负责人交代吧。印象深刻的是我第一次带队到客户现场作需求，连打印机，打印纸，笔记本，网线，小交换机装着满满一大箱一个都不少的带到现场。白天作需求，晚上联机将各自的需求整理成word文档,第二天再给客户确认，反复修改。直到最终的需求评审会议通过后，连夜打印。厚厚的7大本文档（每个业务子系统一本），然后乘以2，客户一份，公司一份。那一晚，一个崭新的打印机硬是被折腾得面目全非啊。第二天大清早，还特地跑到当地的装帧店，将这些文档精美的包装一番，然后各自分头将包装好的需求文档提交给客户方对应的业务部门的经理签名，最后汇总到客户的项目负责人手里存档，自己再带一份回公司存档并作为项目设计的依据。至此，《需求调研报告》就over了。由于项目是客户化定制的，当项目进入到实施过程中的时候，往往需求的变更会占到当初需求调研的30%强，而且你还不能拿当初双方签订的《需求调研报告》来说事儿，来约束客户。除非你是行业标杆，很强势很牛叉。所以当团队将依据《需求调研报告》将《功能规格书》编制出来后，其使命基本完成，转而束之高阁。
    《需求调研报告》要根据客户的描述加以分析和整理成如下要素：数据的输入、输出，业务数据量的大小及使用频率（会据此作性能的特殊设计以及负载测试），参与业务的角色，有无特殊的权限控制，业务流程走向，是否与其他的业务相互关联等等。这些要素不是通过与客户的一次沟通交流就能获取到。要有耐心，要细致，还要有技巧，最关键的是你要懂得客户业务。否则，客户说的你不懂，然后你一张嘴就显外行。最后，你做出来的需求就三字：不靠谱。即使凭客户关系过了评审这一关，报告上客户也签了字，但后等到系统实施上线的时候，你的需求变更基本就朝着80%的比例上奔去了。那时候，先不谈老板会怎样看你，就你旁边那些个开发的兄弟看着自己辛苦的成果一个个被客户推翻，你就知道可以杀人的眼神是神马味道了。
    步子迈得有些大了，扯的有些远了。咱们这里只谈项目文档，关于需求如何作，如何才能做好，需要另起一篇详述。总之，这份文档如果交待的不清楚，会严重影响着项目的质量与进度。说直接一点，就是关系着项目成本或是成败。
    四、《需求评审报告》

    类似于会议纪要性质的文档，是需求评审会议后产生的结果。记录会议的时间，地点，参与的人员，会议的主题，每一项业务需求在会议中是否得到确认〔这一点是整个文档的关键之处，很有可能a部门提的需求与b部门的业务发生冲突，这种事情很常见，将来会在如何做好需求一篇中详述〕。总之，这份报告应作为《需求调研报告》的修正文档，将评审后的结果同步到《需求调研报告》中，也为下一次的需求评审做好准备，这样反复几次，《需求调研报告》才最终得以客户确认。
    五、《项目开发计划》

    开发计划在需求调研需求完毕后就要着手开始制定。计划书里包括设计、开发、测试、实施的具体时间，还要注明每个阶段的关键点。比如，项目第一次构建的时间点，第一次提交测试的时间点，系统发布的时间点，项目验收的时间点等等，都要在计划书中明确标明。如果项目大、周期长，项目还要分为若干个里程碑，每个里程碑要有详细的进度目标及质量目标说明作为里程碑到达的检验标准。另外，每个任务都除了有具体的时间点、优先级之外，还要有任务的责任人和需要客户配合的事项。
    《项目开发计划》 一般分两个版本。一份给客户，一份属于项目组内部使用。两个版本相比较而言，除了规划的粒度粗细有差别外，有时候在不得以的情况下，其时间点也不相同。至于原因，主要是由于客户对信息化的认知程度有限，认为开发系统是一件简单的事情，从而限定的时间要求比较苛刻。但项目合同还得签，计划表还得照着客户的时间限定来做。真正进入项目实施过程中的时候，跟客户保持良好的沟通，让客户理解信息化建设是一个逐步有序的过程，引导客户配合我们的步骤来实施。做好了这一点，我想客户也不会在回头在开发计划上与我们纠结，毕竟，把项目做好才是硬道理。
    项目组内部的开发计划要做好版本控制。比如：一个项目周期较长，分若干里程碑，那么在最初制定计划的时候是允许前细后粗的。也就说，第一个里程碑规划的比较详细，后续的里程碑有意的放粗，而等到前个里程碑将近结束的时候再来细化后一个里程碑的工作内容，因此，《项目开发计划》 的每个版本都要留存，并做好文档的版本变更说明。还有，你一定要相信，项目的执行情况与事先安排的计划定会存在差距。那么就每周召集项目组开来一次项目会议，找出差距，分析原因，最后将计划书完成一次同步。请记住《项目开发计划》决不是由某个人或某些人拍着脑袋弄出来的一份毫无可执行性的文档，它应该是指引项目最终走向胜利目标的航线。
    六、《功能特性列表》

    也可以叫做《功能模块列表》。模块是项目开发计划制定过程中可划分的最小粒度〔一般情况下如此〕，所以，《项目开发计划》必须等到这份文档出品后才能开始制定。
《功能特性列表》的内容包括：子系统名称，模块名称，模块编号。文档由需求调研人员编制，格式简洁，其目的是让阅读者毫不费劲就能了解项目的实质内容以及项目规模。
    七、《功能规格书》

    业内有句话：功能规格书是标杆，每日构建是心跳，里程碑是生命线。由此可见规格书的重要性。他不仅是项目开发的参照，同时也作为测试的依据，所以它也是开发与测试协作的纽带。

   《功能规格书》一般由富有项目经验的开发人员编写，能迅速、准确的根据需求调研的成果转化为可编码开发的功能模块。一份好的功能规格书的标准是让阅读文档的人能够了解系统运转的各方面细节。比如：某个模块的初始界面是什么样，初始加载的数据条件是什么，页面上有哪些按钮，其布局如何，每个按钮如何响应，是弹出〔或跳转〕另一个页面，遇到异常情况的提示信息是什么。不仅是初始页面，模块中的每个页面都要做如此细致的说明，要细致到哪怕是一个下拉框都要说明填充其中的值从哪里获取。每个操作要说明成功与失败的标准,有流程的模块要画出流程图，流程的每一步注明参与的人员〔角色〕。
    功能规格书分阶段写，以划分的里程碑为准。每一阶段的功能规格书完成后，召集项目小组开规格书评审会议。测试人员必须到场，一方面是为了尽早的介入项目，对项目的构成有更直观的认识。另一方面，也可以就前期从《需求调研报告》获得的理解来对开发人员设计的规格书提出自己的意见。评审会议由项目组长主持，每位参与设计的人员轮流上台讲解自己设计的那部分，其余的人员主要从以下几个方面进行评审：
    1、功能设计是否满足客户需求。
    2 、面布局是否美观、合理。操作是否简单、易用。
    3 、据流向是否清晰，模块之间的数据关联设计是否合理。
    4、预计的开发时间是否合理，是否满足项目的整体开发周期要求。
    评审完毕后，各自根据修改意见下去调整规格书。如此反复几个回合，确定了功能规格书作为了项目的标杆。这个时候，项目组的所有成员〔包括测试〕都统一了对项目的认识，规格书进入了冻结阶段，任何人无法修改。接下来，开发人员开始按照规格书中的设计进行编码，测试人员开始根据规格书编写测试用例。
    编写功能规格书〔其实是设计的过程〕是一项繁复的工作，尤其是进入项目实施阶段。用户的需求变更会不可避免的导致系统与规格书的不同步。按照正规的流程，变更首先会导致设计的变更〔规格书〕，设计的变更指导代码的变更。但实际上，项目进入实施阶段后，留给项目组处理反馈的时间往往并不多，再者，一些细微的调整〔比如界面的改动，控件的初始值〕如果遵循正规的流程会使开发人员怨声载道，士气低下。因此，我采用了折中的方法：第一次设计一气呵成，必须保证实际运行的系统与设计同步。这一点由测试部负责监控。系统上线后，同步的工作可以专门抽个时间来完成。即，前期是系统参照规格书开发，后期是规格书参照系统来同步。在频繁的修改下必须保证一周内至少同步一次，并且将文档提交给测试部检查，出现问题，以bug论处。那有朋友会问，既然规格书在后期失去了标杆的作用，那还费时费劲的同步它有何意义？
    1、对项目后期维护起至关重要作用，完整的设计文档在加上良好的代码注释，会让维护人员迅速的进入项目状态。
    2、让新进入项目组的成员能尽快的对项目有整体的印象，从而担任工作。另外还可以减少项目培训的成本。
   然而，后期的同步又引发了另一个棘手问题：测试人员对需求变更的测试标准从哪里获取呢？于是我们又做了改进，当需求变更到项目组手里后，召开会议，测试人员参加。会议上，对小的、简单的修改当即提出解决方案，测试人员记录，以此作为测试依据。对于大的改动〔有可能会增加功能模块〕，则还是采用先设计后开发的原则。
    八、 《详细设计报说明》

   作为《功能规格书》的一份补充文档，主要解决如何编码的问题，测试人员一般不看。开发人员在编码之前或编码过程中如果遇到了复杂的算、业务逻辑，可以在该文档中详细的说明解决思路，也可以用一段伪代码来说明。
    九、《数据库设计报告》

    该文档与《功能规格书》配套。规格书中关于数据库设计的说明直接引用该文档。另外，项目验收时，客户也常要求开发方提供数据库设计报告，作为日后其他系统与本系统做接口的依据说明。
    《数据库设计报告》记录的内容有：模块名，数据表名，英文字段名，中文说明，主键，外键，索引，约束〔注明关联的表及字段〕，数据类型，长度，能否为空以及对整张数据表的备注信息。对于某些关键字段还要对他的值所表示的含义做详细说明。另外，《数据库设计报告》也会面临后期同步的棘手问题，其同步的策略是做了修改就立即同步〔数据库的改动较少，且简单。这一点与规格书还有所不同〕。
  数据库设计报告的评审与规格书相同，评审依据有如下几点：
    1、是否留有适当的冗余便于系统的扩展。
    2、性能是否能达标。索引是否合理。
    3、数据字段描述是否清晰易懂。
    评审通过的数据库设计报告交给测试一份，测试人员会针对具有特殊性能要求的模块编写脚本做压力测试。