软件开发中文档的编写是一个不可缺少的环节,常见的如《需求分析》、《概要分析》、《数据库设计》等。在“软件人”的阵营里向来存在两种观点,注重文档还是关心代码。一直争论多少年了,好像都没有一个真正的定乱。如果大项目且开发周期相对合理,很多时候项目组一定会安排进行相关开发文档的编写;但对于周期短工作量又多的时候,可能很多项目组就会选择代码编写为第一的原则,相应的文档编写很多时候被安排在项目演示甚至交付后才进行补救式的操作,而且这样的文档很多都是归于应付客户要求的形式罢了。
项目周期与质量保证向来是相矛盾的,如果为了保证质量消耗时间去编写文档,必将压缩系统开发的时间;不进行开发文档的编写,又没法进行开发质量的保证。那问题就来了,开发文档是否需要编写?怎么写?谁来写?
首先,我们来讨论下开发文档编写的必要性,即要不要编写开发文档;这些开发文档是否就一定能在开发中指导我们的程序员编写代码;在运维中支撑维护人员解决问题等。
“高楼万丈平地起”,这里告诉我们,一座高楼是否可以建?怎么建?建多高?最终由地基来决定。没有地基的牢固支撑,你建的楼就会变成“低楼”、“危楼”、“烂尾楼”。高楼需要地基的存在,需要地基的支撑,没有这两样又想要高楼,那只有去找“空中楼阁”了。那这个地基的牢固与否又是靠什么东西决定呢?“设计图纸”,对就是设计图纸,没有图纸上专业化的设计和演算规划,创建牢固的地基那就是天方夜谭、痴人说梦。
回到我们的软件项目中来,一个项目的成功同样需要一个牢靠的地基,有了这个地基才能装载那些各付其职的功能模块。这个地基就是我们软件的《架构设计》和《概要设计》,没有架构的设计就不能确保整个系统稳定的运行与统一处理方式等;没有概要设计,客户怎么知道当前需要能完成那些功能,程序员又如何得知自己编写的功能模块针对的业务处理流程,当然更不可能保证数据逻辑处理的正确性、完整性。不用再讨论下去了吧,光这两个问题,就能足以说明文档编写的重要性了。
还是举例说下吧,看上面的文字多少有点空泛,我这里写一个《用户信息模块的概要设计文档》,只列举主要内容了(仅供参考)。
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还是其他)统一。
因为我这里说的仅是开发文档,所以像《用户手册》、《培训计划》、《验收计划》、《安装步骤》等就没罗列了。不是说它们不重要,只因为它们不属于开发文档的范畴罢了。实际开发中,需要完成什么样的文档完全取决于当前项目的开发、实施背景和用户需求,有些文档本就是做给客户验收的。(我曾经做一个电子政务系统,甲方请了监理公司在实施过程中参与,结果搞得各式各样的文档都需要完成,尽管其中很多都是些形式东西,但没法子,客户就是上帝。)对于客户要求这类型的文档我们不一定要做细、做专,做体面才是最有效的。反之,对于项目开发中特别是代码编写的指导文档,就必须要求编写得简单明了,面面俱到。
原文出处:http://www.cnblogs.com/warison2008/archive/2010/07/07/1772756.html