合作开发后谈如何写文档

从4月3号到5月7号机房收费系统合作版终于告一段落。从写文档到画UML图，到加设计模式对文档进行补充，然后是编码，测试发布。时间持续了一个月，遇到的问题很多，当然收获也很多。

由于之前已经做过几遍机房收费系统了对系统的功能已经很熟悉了，所以这次合作开发就省去了可行性分析、对系统功能的具体分析等工作，那么接下来就是写文档了。虽然之前个人版机房收费系统已经试着写过文档了，但那些文档基本上都是写给自己看，多点什么内容无关紧要，少点什么内容自己也察觉不出来，毕竟个人版的系统涉及到的所有人员只有自己一个人。但合作开发就不一样了，合作开发要求项目要文档来驱动，所有的东西都要体现在文档上，避免直接交流都要以文档来代替。一开始写文档时真不知道如何下手，该从哪去写，各个文档里都要具体写什么内容。怎么写才能体现出系统的设计思路及实现思路以方便小组成员开发的时候参考。

这次合作开发主要写了可行性分析、需求分析、概要设计、详细设计、数据库设计、测试计划、项目开发计划、用户操作手册几个文档。比较重要的是需求分析文档、概要设计文档、详细设计文档、数据库设计文档还有就是测试文档。

需求分析

需求分析，需求分析是系统设计的前提，一个系统设计的是不是合理，功能是不是完善主要看需求分析阶段的需求分析做的好不好。作为软件的设计者来说，需求分析文档是写给客户看的也是写给自己看的。写给客户看主要是看有没有把客户的所有需求考虑在内，体现在功能、界面设计上。客户看到需求文档并满意后开发人员才能开始开发系统。如果将来软件开发出来客户对软件有了变动，认为没有达到他的需求此时需求文档完全可以作为一份凭证，证明责任并不在我们开发人员身上。当然需求分析文档最主要的还是写给软件设计人员自己看的。对于一个系统来说在各个方面都有要求，比如数据的输入输出、界面设计及系统所涉及的各项功能等。对于一个软件设计师来说这些记在脑子里是没用的，因为软件设计师并不参与软件的实现过程，在软件的实现过程中编码人员需要这些数据，而作为软件设计者能为编程人员提供这些数据的一个平台只有通过文档来体现。所以需求分析文档的主要的内容可以概括为软件原型图（为用户提供一个软件开发参考）、用例图（向软件设计者、软件开发者提供系统功能模型）、数据输入、输出介绍（为软件设计者、编程人员提供数据参考）。

概要设计文档

概要设计文档主要是对系统的一个概要分析，是从整体上看系统的构成，如果把整个软件当做一本书来看，概要设计文档就应该和书的目录的作用差不多了，是对书内容的整体的描述。所以在概要设计文档里应该体现的内容应该包括系统架构（包图）、类图、接口设计、数据库表说明等。站在使用者的角度来看，当然概要设计文档是写给项目开发人员用的。概要设计体现出对软件的宏观把控，内容不多但却十分重要为软件详细指明方向。

详细设计文档

概要设计是对整个系统的整体描述，详细设计文档就是在概要设计的基础上对系统设计的具体实现和完善。详细设计文档对于分层实现和合作开发来说十分重要。软件实现人员（编程人员）首先要对系统有一个快速认识、了解，所以详细文档中系统的整体架构必不可少。有了对系统的整体认识，在软件具体实现上用到的最多的还是类，开发人员需要实现他们并去使用他们，所以详细设计文档中对类、类中每个方法的功能描述、属性的使用、参数的类型和使用等描述都是必不可少的。当然一个系统的实现不仅仅体现在单个类的实现上，还体现在多个类的协同上即类与类之间的调用。所以详细设计文档中第三个必不可少的内容就是时序图及其描述。时序图体现出在整个系统中或某个功能模块中类与类之间的联系及类与类之间的数据传递。把系统中的类看做节点有了时序图做向导才把这些离散的点连起来组成网，从而构成了整个系统。

数据库设计说明书

数据库设计说明书主要体现数据库的设计跟使用，所以数据库设计说明书中应详尽的描述数据库的概念结构设计、逻辑结构设计和物理结构设计，当然数据库名称、数据表结构、各表字段及详细说明、及视图的说明都必不可少。数据库是整个软件应用的根基，是软件设计的起点，它起着决定性的质变作用。站在数据库的建立者和使用者的角度来看，数据库设计说明书不仅要能够使数据库创建者能够完成一个完整的数据库设计，还要使数据库使用者能够在此说明书的指导下实现对数据库的使用。

测试计划文档

测试文档可千万不能小瞧，一个系统开发完成，成功与否要看测试效果如何，测试效果的体现还要根据测试计划文档来评价，它直接体现着开发人员所开发出的系统是否跟软件设计人员设计的系统之间的差距。所以测试文档中应该体现出对各模块功能测试的测试内容、测试方法、测试结果预测等。测试文档主要的使用对象是软件测试人员，是衡量一个系统是否成功的关键性文档，也为后期修改指明了方向。

合作开发文档的不足

这次合作写的文档明显有许多不足之处，问题主要体现在详细设计文档和测试计划文档内容不详细，有些关键的细节东西没有体现出来。这次开发我负责写文档、画图和U层，坤哥负责B层跟抽象工厂，静媛负责D层、接口跟数据库。U层的问题还少点，这可能跟由我负责有关。B层是出现问题最多的层，主要的问题是详细设计中体现的供代码实现的信息太少，比如说各个方法的功能及实现及所需要的参数的说明等。最突出的一个问题是从D层返回给B层的DataTable数据，如果这些数据直接返回给U层还好说直接返回就行，当这些数据在B层需要的时候由于DataTable不像实体那样对象名打点就能得到所需要的数据，所以对于坤哥来说DataTable就像一个密封的容器，明知道里边有数据但只能眼睁睁的看着却拿不到。D层跟数据库出的问题主要是在数据表的查询和字段的使用上。比如查询正在上机时，可以根据IsOnline字段来判断当前正在上机信息，由于信息没体现出来所以该字段没有用上基本上都是根据下机时间、日期是否为空来判断的，虽然这么做能够实现功能但与预期的实现方式有差别。还有一个突出问题就是有些字段的值是固定可选择的，比如说IsOnline字段的可选择值为”是“或”否“，IsCheckout字段的可选择值为“是”或“否”，还有就是上机记录的备注信息“Comment”的可选择值是“正常下机”和“全部下机”，由于这样的数据没有在文档中将可选择的值全部体现出来，所以测试的时候导致了数据库中的值各种各样。

总结：

写文档最最重要的是要明确使用对象，几个文档的使用对象包括客户、设计人员自己、编程人员、后期维护人员，所有文档的建立要站在使用者的角度去考虑文档应该怎么写、写什么，所以写文档要牢牢把握为谁而写。其次文档还要明确的体现出设计思路及实现思路，要让编程人员按你的设计思路和实现思路去实现。所以衡量文档是否成功的标志是软件的实现是否跟设计人员的设计思路和实现思路完全吻合。