软件开发项目管理的案例解说(三)
来源:广州软件开发 编辑:广州软件开发公司 日期:2017-03-20
软件开发设计规范书的撰写 —系列 (三)
引言
在上一期(今年五月份)的《程序员》杂志里有关软件开发项目管理的系列文章中,我以自己曾经从事过的开发微软嵌入式操作系统的项目管理作为案例,讲解了制定开发项目计划的一些关键管理概念和实践指南,包括项目时间表的制定流程、如何确定每个开发阶段的里程碑、如何制定衡量是否达到开发里程碑的终结标准,等等。文章中还提到完善的软件开发项目管理要求管理人员在制定项目的执行计划时间表的同时,还要同时照顾到体现软件本身的设计计划,而这个设计计划是用软件的设计规范书(也叫Design Specification,或简称Spec)来总结的。
在这篇连续文章里,我来进一步讲解软件设计规范书的撰写,包括可供查照的撰写模版提纲、如何总结使用界面的设计、如何总结出错信息等,以及微软在这方面的良好企业文化传统。你要是能够使你的开发团队在项目计划阶段也采用类似的设计计划,对推动你们的开发成功会有很多好处。
软件设计规范书的撰写提纲
功能规范书是整个开发团队用来进行设计交流的最主要的文件和手段。它陈述、归纳、总结了一个软件产品或系统中所有的功能设计的具体细节。在一个软件产品或系统最终完成和成型之前,功能设计规范书是整个设计构思的中心。所以它是整个软件开发项目的中心指南文件,也可以说它是开发计划安排的基石,因为它也为其它的开发计划提供一个参照的标准。
首先,作为软件开发者,你应该充分重视在开发之前将软件的使用功能的设计先进行全面的总结并以文档作记录的重要性。不同的开发者和开发团队对如何进行这样的使用功能的总结有很多不同的习惯和方法,但是不管采用何种方法,将所需要开发的各种使用功能的设计用文件固定下来,为软件开发会带来巨大的好处:
• 就像为盖房子提供一个蓝图那样,Spec为整个软件的功能开发提供一个完整的规划:需要开发的功能应该都被总结在设计规范书里,规范书里没有的则不该开发。有这样的明确定义,能帮助开发团队避免无效开发、也能帮助测试团队建立有的放矢的测试计划。
• 它为整个开发团队提供一个可以共同参照的统一标准:任何功能开发上有疑问的,都以设计规范书所总结的要求来解决。同时,其它各种有关的项目计划,如测试计划、文件编辑计划、可用性计划、本地化计划等各种计划,都以产品的设计规范书作为它们的计划准则。
• 它为项目的赞助者、客户、以及项目参加人员提供一个对功能设计进行审核、对照、和解决问题的共同讨论点和对证:开发团队的成员以它来协商对设计的建议和意见、对设计提出疑问等等;另外,客户对设计规范书的审核的认可与通过,则表示他同意了被总结了的所需要开发的功能的范围、同时也表示他同意了不要求开发规范书里没有总结的功能。
那么,一个完整的设计规范书应该包含那些内容呢?对不同的开发项目,设计规范书的着重点和范围当然会有些不同,但从总体上来说,如果能对以下这些内容都有明确的定义和总结,在很大程度上能帮助开发团队明确理解功能的设计和开发的目标:
软件产品设计规范书的撰写提纲和模版
1. 文件的梗概和介绍:
• 总结:在设计规范书的起头,对整个开发项目做个总结。用简单几个段落从宏观的高度对整个项目的目的,和它所开发的功能做一个描述。
• 范围:说明设计规范文件的所叙述的范围,包括文件中各个分部的内容大纲。
• 读者:简要地描述阅读和理解此份设计规范文件的读者、以及必要的前提和知识背景。
• 文件的修订历史:注明这份文件的自初稿后的所有修订历史,包括修订日期、改动的内容和理由、谁作的修改,以及修改内容的页数。
2. 开发项目的目标:用段落文字总结以下这些内容:
• 远景:总结整个开发项目的远景,也就是开发的战略目的或目标的定义。
• 设计目标:陈述开发的结果所需要具体解决的问题,以及为达到这些目的所做的相关功能设计的概述性总结。
• 项目理由的辩护:说明为什么需要进行这个项目、开发这个功能或产品。
• 项目的客户和合作者:列出项目开发出的结果所要服务的具体客户,以及项目进程中所要依赖的合作伙伴、包括企业内部其它部门的合作者和企业外部的合作者。
• 项目的风险以及成功的依赖者:列出整个项目的所面临或可能会遇到的风险。
• 项目进度的里程碑:用表格的方式将整个项目的里程碑给详细地列出来,并将每个里程碑完成结束的衡量标准也做总结陈述。
• 使用方案和系统流程图: 用逻辑图或其它图像来说明系统的数据处理的流程、各种组件单元之间怎样互相配合来提供所设计的功能,以及注明各种数据的输入、输出、和处理等等。
3. 功能需求的总结:在这一章里详细列出软件所有应该开发的功能。每个功能应该有相对应的客户使用方案为基础。最好的方法是用表格的方法,逐步列出产品必须支持的使用方案,以及每个使用方案所依赖的功能。
4. 功能的具体设计:在这一章里详细总结和列出软件所有的功能的具体的设计。对每个具体的设计进行详细的陈述,并配之于所需要的图像进行解释。对每个具体的设计进行包括以下内容的详细的陈述:
• 所提供的功能、性能、或其它服务。
• 使用界面的解说,包括软件总体的运行界面的框架、不同的视窗的功能、菜单(Menu)、工具条(Tools Bar)以及按键(Buttons),状态条(Status Bar),图释(Icon),以及每个对话框(Dialog Box)的设计和形象,产品的徽标(Logo),启动画面(Splash Screen),等等。它们还应该包括每个控制键以及输入时段的使用法,以及系统的反应和回馈的行为;以及每个出错的信息、格式、和具体的文字,等等。
• 产品使用说明(Online help)的设计、连接、内容要求。
5. 设计的考虑因素:总结其它设计中必须满足的要求:
• 运行平台的要求:此产品或系统对运行环境的各种要求, 如操作平台、硬件、网络连接、使用规章等等。
• 性能要求及可以接受的衡量的准则,以及对产品安装的功能、安全性, 国际化和地方化的要求等等。
6. 开发时间表:列出该项目的开发时间表,对每一具体开发任务所需的人力及时间的初步估计, 及所有的项目里程碑。
7. 项目成功所依赖的因素:总结对所有可以估计到的外在制约的因素, 特别是写明哪些因素是该项目成功所依赖的, 如特别的人才, 设备, 所需的技术、某些外部团队的支持或必须完成的组件,等等。
7. 未解决的问题:总结和列出任何尚未解决的问题, 或有待近一步调查商讨才能定出答案的有关设计方案和计划, 及任何与客户间尚未同意的事项, 等等。
结尾页:设计规范书通过的签字——当设计文件最后审核通过后,各团队领导和客户代表在此签字。
制定明确的界面设计
除了按照上面所讲的按照特定的模版来进行设计规范书的撰写,以保证很多重要的东西不至于被忘记或遗漏、使得从事设计的项目经理和开发团队的成员们不得不去思考和解决相关的一系列问题,另一个重要的帮助提高软件开发功能规范书质量的关键是,所有软件的使用界面的设计必须要有明确的定义和说明。
设定明确的界面设计指的是,软件的使用界面应该在软件开发之前都已经设计好了、并在设计规范书中进行详细的总结和解说,这样开发团队的开发工程师们在进行程序开发时就有一个明确无误的参照,不仅知道开发出来的软件的使用界面应该是怎样的,更重要的是,使用界面在被使用的过程中各个控制组件应该如何反应、软件应该如何给使用者准确的回馈、使他们能够完成必要的使用方案(也叫User Scenarios,即软件功能使用的过程和顺序)去解决具体的问题,开发工程师们事先就有一个可参照的准确的 “蓝图”。要是没有这样详细的设计,开发工程师可以临时发挥去任意开发。那样开发出来的结果也许有时是可以满足要求的,但在很多情况下往往是无法满足要求而造成浪费的无谓开发。合理的软件开发的项目管理,就是要尽量减少和避免这种无谓的劳动和浪费,而要使每个被开发出来的功能、每个使用界面的组成部分,都有它们明确的目的、都是为了保证使用方案的完满的执行而能起到它们的作用,设计规范书中明确无误的界面设计总结就是关键。
下面我仍将自己在微软进行过的嵌入式操作系统工具的开发项目管理作为案例,来举例说明如何设定明确的界面设计。
从图1中你可以看到,使用界面的设计不仅要显示界面看起来应该是什么样,更要有对各个界面的控制组件的行为和回馈有详细的解释,比如“按了这个键后会发生什么……”、“在这个对话框里输入数据后会发生什么……”等等。有这样的详细的图像解释,不仅开发工程师们有开发的依据,测试工程师们也能够根据这些具体的要求进行测试方案的制定、文档编辑们也能够根据这些具体的界面行为来撰写使用说明书。这也是为什么详细的界面设计对完整的设计规范书那么重要。
图2是另外一个类似的例子,你可以看到这里是两个Tree View列表的界面设计。如同上面举例的概念一样,这里对Tree View中具体的细节也要做说明,包括图标、文字显示、按键等。用类似这样的界面设计的图画,再配上对很多具体的界面的细节加以说明的图示文字,能使设计的概念很容易与开发人员沟通,并使他们在开发时注意到这些重要的细节。这是一种极为有效的设计总结方法。
当然,在设计规范书里对这样的界面设计光有图画是不够的,对每个界面设计的组成部分还应该再配上具体的文字解说。最有效的方法是将每个界面的组成部分标明他们的重要性优先权的(Priority) 划分、每个组成部分的名字、以及具体的行为细节,用列表的形式作总结。这样在设计规范书进行团队审核的时候可以很方便地进行逐条讨论,而这样的格式又可以为开发工程师们提供一目了然的参照。下面图3是设计图像配上文字解说的例子(我将原来的英文产品设计附上翻译便于阅读)。
图像界面设计总结—— 状态条(Status Bar) 的功能设计
里程碑 图像界面组成部分 界面的使用和反馈行为
M1 Status bar – Filed 1: General Status text
状态条 – 第1个数据显示栏:普通的状态文字 • Default text: Ready
• It displays other status text by the tool, as specified elsewhere in this spec.
• 默认值文字:可正常使用
• 其它时候显示此设计规范中其它地方所指定的工具的状态文字
M3 Status bar – Filed 2: Progress bar
状态条 – 第2个数据显示栏:渐进显示条 Progress bar, displayed during adding dependencies and build process, etc., whenever TD is running a background task for more 2 seconds.
在检测其它依赖组件以及操作系统镜像生成时候,每当工具需要有2秒以上的等待时间时,显示渐进显示条。
M2 Status bar – Filed 3: Total footprint size
状态条 – 第3个数据显示栏:显示操作系统镜像的大小总数 Total footprint size
• When no configuration is loaded, it displays blank.
• Once a configuration is loaded, it displays total uncompressed footprint size, in MB size with one decimal fraction.
操作系统镜像的总数显示应该是
• 当没有一个镜像设计被装载在工具中,不显示任何数字。
• 当一个操作系统的设计镜像被装载在工具中后,显示以兆为单位的、带一个小数点的、非压缩的操作系统镜像的大小总数。
M4 Status bar – Filed 4: Database
状态条 – 第4个数据显示栏:显示所连接的数据库的名字 Current connected database:
• When TD first invoked and no DB is connected, it displays blank.
• Once user specifies the database to use, the DB name is displayed in this field.
显示目前工具所连接的数据库:
• 当工具刚启动时,还没有数据库连接上时,不显示任何数字。
• 当一旦连接上数据库后,显示数据库连的名字。
不要忽视出错信息的设计
在软件设计中,我们不可避免地要碰到对各种可能出现的错误,如使用者所犯的错误以及软件本身的缺陷带来的系统错误等,提供回馈的出错信息(Error Message,也叫错误信息)的设计。明确和有效的出错信息的设计,也必须是完整的设计规范书所应该包括的内容。出错信息的设计的好坏,直接影响到一个软件的可用性,所以是任何软件开发者应该重视的设计因素之一。
在微软的产品团队,我们的界面设计对出错信息的质量非常重视,因为以前微软有的产品对这方面不够重视,造成一些非常荒唐可笑的出错信息被加入到产品中去,而常常成为业界的笑柄。最有名的一些可笑的出错信息包括 “You just did something you shouldn’t do.”(你刚做了个不该做的事),“An unknown error has occurred”(一个不知怎么回事的错误发生了),“A catastrophic error is going to happen”(像大灾难似的错误将要发生了)等等。现在微软从事界面设计的团队还有一个专门刊登记录所有这些可笑的出错信息的网站,叫做“UI Hall of Shame”(令人羞愧的界面设计大展览),将全公司各个产品团队任何被发现的荒唐出错信息设计登在上面,以此告诫所有开发者们不要忽视出错信息的设计。下面这个出错信息对话框就是其中的展出之一:“呃哟糟糕,也许会出现个问题。还要继续下去吗?”
对任何出错信息的设计,都应该按照下面这个设计原则来进行,
1. 出错信息首先应该向使用者明确说明,究竟发生了什么问题或错误;
2. 出错信息应该向使用者解释是何种原因造成了出错,即到底是因为使用者的错误、使用还是系统本身的问题造成了问题;
3. 出错信息还应该向使用者提示,应该采取什么样的措施、或纠正的步骤,来纠正错误或避免错误,使得使用者可以继续使用软件。
所有的出错信息的设计必须通过设计规范书进行全面的记录和总结,然后在程序开发时开发工程师要根据这些设计来开发。也就是说,任何出错信息都必须是事先设计好的,而不应该由程序编写者心血来潮似地任意加入到软件中去。在开发过程中要是发现有新的出错信息需要加入产品,加入的过程同样要按照设计的要求进行,在对设计规范书经过修改、加入新的设计之后,才能进行程序的改动。这样的严格管理方法是避免荒唐可笑的文字混进产品中去的最有效方法。
在下一期的文章里,我们再来看如何制定执行良好的开发执行管理,来帮助我们开发高质量的软件。
相关阅读