软件开发中文档的编写是一个不可缺少的环节，常见的如《需求分析》、《概要分析》、《数据库设计》等。在“软件人”的阵营里向来存在两种观点，注重文档还是关心代码。一直争论多少年了，好像都没有一个真正的定乱。如果大项目且开发周期相对合理，很多时候项目组一定会安排进行相关开发文档的编写；但对于周期短工作量又多的时候，可能很多项目组就会选择代码编写为第一的原则，相应的文档编写很多时候被安排在项目演示甚至交付后才进行补救式的操作，而且这样的文档很多都是归于应付客户要求的形式罢了。

项目周期与质量保证向来是相矛盾的，如果为了保证质量消耗时间去编写文档，必将压缩系统开发的时间；不进行开发文档的编写，又没法进行开发质量的保证。那问题就来了，开发文档是否需要编写？怎么写？谁来写？

首先，我们来讨论下开发文档编写的必要性，即要不要编写开发文档；这些开发文档是否就一定能在开发中指导我们的程序员编写代码；在运维中支撑维护人员解决问题等。

“高楼万丈平地起”，这里告诉我们，一座高楼是否可以建？怎么建？建多高？最终由地基来决定。没有地基的牢固支撑，你建的楼就会变成“低楼”、“危楼”、“烂尾楼”。高楼需要地基的存在，需要地基的支撑，没有这两样又想要高楼，那只有去找“空中楼阁”了。那这个地基的牢固与否又是靠什么东西决定呢？“设计图纸”，对就是设计图纸，没有图纸上专业化的设计和演算规划，创建牢固的地基那就是天方夜谭、痴人说梦。

回到我们的软件项目中来，一个项目的成功同样需要一个牢靠的地基，有了这个地基才能装载那些各付其职的功能模块。这个地基就是我们软件的《架构设计》和《概要设计》，没有架构的设计就不能确保整个系统稳定的运行与统一处理方式等；没有概要设计，客户怎么知道当前需要能完成那些功能，程序员又如何得知自己编写的功能模块针对的业务处理流程，当然更不可能保证数据逻辑处理的正确性、完整性。不用再讨论下去了吧，光这两个问题，就能足以说明文档编写的重要性了。

       看到这里你可能会里面跳出来驳斥我的谬论，理直气壮般告诉我，我们的项目没有《架构设计》和《概要设计》也做的很好啊。我们是没有《架构设计》，因为我们压根儿就不需要它，我们的架构已经是多年成型的东西，很完美，进行了不同层次的封装，提供了丰富多样的扩展接口。有了这样成熟的系统架构而且是已经实现的东西，为什么我们还需要《架构设计》，莫名其妙。我相信你说的这些，你们的架构很完美，相当健壮，可扩展性又丰富，我承认这些都是好框架必须具备的，你们的框架也是好框架。但我能否问下，你们的这个完美是如何诞生的？如果是公司内部自行研发的，那敢肯定一定存在设计文档；如果是某个牛人自己磨练出来的，那就有点担心了，万一这个牛人走了如何是好？难道你们告诉客户，我们的架构有问题，不做这个项目了？夸张！！！我又问，你们的这个完美是否存在缺陷？如果你说不存在，那我只能伸手摆个pose，鄙视你的年幼无知，如果你说存在但是不知道，那我只能送你两个字——“杯具”；我最后问，你们的这个完美是否可以兼容所有的企业运用？是否能支持J2EE、J2ME、J2SE的解决方案？要是你告诉我说仅支持J2EE，因为我们只作J2EE的项目。你是老板吗？说这样的要负责任的，不然被老板听见，小心砸你饭碗。

       说完文档编写的必要性，那就来说说如何写的问题。其实很多时候一个成熟的软件公司或项目组都会有一套成型的文档模板，当然这些模板很多可能是从化为、东软等大型软件公司变种出来的。有了这些定型的模板，那编写文档的工作就会轻松很多，我们需要做的就是在相应的模板中填充自己的相关描述，即可形成针对当前项目的开发文档。

还是举例说下吧，看上面的文字多少有点空泛，我这里写一个《用户信息模块的概要设计文档》，只列举主要内容了(仅供参考)。

1 功能描述：用于完成系统用户信息的新增、删除、修改、查询；

2 功能用例：一个主用例用户信息，附加新增、删除、修改、查询4个子用例，操作人员为管理员，图形就不画了，很简单的；

3 业务流程：查询有效范围用户信息——》新增用户信息——》判断当前帐号是否存在——》存在给出提示，反之保存成功提示。（简单的说下，图形就不画了）

4 约束限制：

超级管理员可操作所有（包含删除，我这里考虑仅是逻辑删除、非物理删除）的用户信息；

系统管理员可操作除系统管理员、超级管理员外的全部用户信息；

单位管理员可操作本单位用户信息；

用户帐号信息系统内全局唯一；

5 系统性能：

要求同时支持500个并发操作；

页面操作响应时间小于1s；

页面大小小于1kb；

当前用户所属员工信息不存在时，可直接进行员工信息的添加，并完成用户信息的同步保存，确保事务的完整性；

6 运行环境：依赖系统整体运行环境为准（存在特殊需要注明）；

7 操作实体：用户信息、员工信息、系统日志等（我不知道，大伙在除概要设计时候是否已完成数据库/实体设计了。）；

8 异常处理：如果系统框架中已经提供相关说明，这里仅需要注明符合系统架构异常处理方式即可。

9 外部接口：输入——用户ID，输出——用户信息；

10 其他说明：用户帐号必须定义为字母开头，数字与字母组合，并保证全局唯一；用户密码采用md5算法加密，系统架构已提供相关接口。

11 注意事项：用户帐号不能为空，不能存在空格，不能超过6位；超级用户信息仅在系统初始化中完成其信息写入操作，其他用户无权对其进行修改；

罗列几个文档的要素，这些我觉得是你的模板一定需要定义的：

1 变更版本记录、参考文献、编写人员、审核人员等；

2 制作背景、使用范围、文档作用；

3 文档结构描述、纲要描述、目录描述；

4 辅助编写工具（如viso\rose等建模工具都可以画用例图，但只能选择一种）、文档格式（word、 pdf还是其他）统一。

       项目组中也不是所有人都必须参与文档的编写，通常业务需求人员、设计人员、架构师、项目经理、小组长占大多数，而且这些人中很多也不是专注于写代码的角色。这就是项目组内部分工协作的事情了，毕竟最大限度地发挥项目组各成员的综合能力才是最主要的，“各司其职，各负其责”方是上策。

因为我这里说的仅是开发文档，所以像《用户手册》、《培训计划》、《验收计划》、《安装步骤》等就没罗列了。不是说它们不重要，只因为它们不属于开发文档的范畴罢了。实际开发中，需要完成什么样的文档完全取决于当前项目的开发、实施背景和用户需求，有些文档本就是做给客户验收的。（我曾经做一个电子政务系统，甲方请了监理公司在实施过程中参与，结果搞得各式各样的文档都需要完成，尽管其中很多都是些形式东西，但没法子，客户就是上帝。）对于客户要求这类型的文档我们不一定要做细、做专，做体面才是最有效的。反之，对于项目开发中特别是代码编写的指导文档，就必须要求编写得简单明了，面面俱到。

 （注：本人文章均为原创，转载请注明出处！20100619写于深圳。）