关于概要设计文档的写作
Author:魏雷远 Date:2007-06-12Email:leiywei@163.com
题记:算是一点经验和学习心得吧。如果有疏漏之处,还请大家慷慨补充,先在此谢过。CC:如果进行转载,请声明是转载的我的,我仅有少数文章有这样的要求的。
〇、概念概要设计文档是一个框架设计文档,指出了设计的大体思路。与详细设计文档不同,它没有详细设计文档描述的细致入微。但是一份好的概要设计文档,对于一个高级软件工程师来说,完全有能力进行系统实现了。
一、一般格式文档格式如同人的相貌,以貌取人,虽然不合理,但是有它的普遍性。下面给出一个范例:
1.0文档的封面封面是最笼统的概括,一般包括文件名称、文件编号、项目名称、项目编号、文件密级、文件版本、文件作者、文件状态等信息。例如:XXX公司技术文件(居中)文件名称:XXX概要设计文件编号:A00-B00-000XXX(编号符合自己公司的标准即可)项目名称:XXX项目(写自己的项目名称)项目编号:A00000XXX(符合自己公司的标准)文件作者:魏雷远文件版本:A(按什么编号都可以,可以为阿拉伯编码、希腊字母编码等) 文件状态:PRE文件密级:绝密......对于有版本控制的文件,还要有版本变更的记录,审核人,审核日期,批准人,批准日期,修订信息等。
1.1文件修订页文件修订页的目的是记录该文件的详细修改记录,一般包括修改的章节、内容、日期、修改人、批准人等等。按表格形式进行记录
1.2索引和目录这部分可以根据概要设计文档内容自动生成。不熟悉Word者,按如下操作:插入菜单->引用->索引和目录,按照提示进行操作。
1.3文件正文部分此部分是概要设计文档的核心部分。
下面给出我做的项目(软件)的一个范例:
1.范围
1.1系统概述简单描述系统结构或组成。
1.2文档概述简要描述概要设计文档涉及的内容以及适用的对象。
1.3术语与缩略语解释概要设计中的术语和缩略语。===当然,还可以加入其它内容。
2.引用文档列出参考文档或者依据。
3.总体设计
3.1软件体系结构描述软件体系结构,一定要给出图来,直观、清晰、简单、明了。
3.2子系统间的关系列出组成软件的各个子系统间的相互关系。还是要给出图来。
4.子系统设计这部分根据划分的子系统分别描述各部分的功能。说明简单的数据流程即可。细节部分在详细设计文档中体现。
二、说明
2.1与需求文档的关系概要设计文档是需求文档的输出,使需求的一个实现轮廓。也就是说,在概要设计文档中可以看出系统的大概面貌。打个比方说,如果需求文档要求做一个石油行业MIS系统,用于销售的。那么概要设计要确定这个系统的架构、主要功能模块:数据录入、统计、查询、修改、分析等。以及这些模块的大概组成。如分析模块,需要确定数据的分析算法。
2.2与详细设计的关系概要设计文档是详细设计文档的输入。详细设计需要对此进行细化。用程序员利于理解的话来说,概要设计好比F10(Step Over),详细设计好比是F11(Step In)。
2.3文字和图表无论是什么文档,画一幅图,生于长篇大论。图形就是简单、直观、清晰、明了、通俗、易懂。让人一眼看出整体结构来。文字的话,还要让人去理解,碰到不认识的字或者单词就更郁闷了。
三、总结
文档作为项目的重要参考,是进行维护的保证,同是属于企业的产品。文档需要进行合理的管理。当然了,要写好文档,如果在Windows平台上,请懂一点Office中Word,Excel,Visio等,其他工具Rose等,最好也要掌握一些。
后记:有时候,当我看到某公司的PM在不懂技术的情况下,同时不会用word,不会用excel,写出来的文档还赶不上本科生的毕业前,而深感他们需要在这方面提高一下自己的素质。我们只需要掌握Office功能的0.5%,那我们可以写出非常漂亮的文档,给阅读者以美的享受。
祝愿我们大家都有一个健康的身体,去挑战我们的未来。