-
2018-11-18 14:42:25
软件设计文档主要包括:业务需求规格说明书、软件需求规格说明书、详细设计规格说明书三部分,三个文档结构类似,内容相互关联解释,业需详细的介绍业务流程,软需采用信息化方式描述业务需求所需的功能信息,详细设计对软需的功能进行详细介绍说明。
一、业务需求规格说明书文档结构
1、概述:主要涉及业务背景和总体目标;
2、主要依据:相关国家政策和制度规范;
3、现状分析:当前业务现状分析和所建设的信息系统整体介绍
4、业务描述:4.1:业务目标;4.2:组织单元(岗位职能);4.3:业务流程(流程图及流程说明);4.4:业务活动(相当于系统功能及功能页面信息介绍);
5、共享融合需求分析(系统之间的集成);
6、附录(业务信息表即字段信息)。
二、软件需求规格说明书:
1、概述:编写目的、术语及参考资料;
2、标准和规范:引用的相关标准和规范;
3、相关假设、限制、依赖条件;
4、功能规格:4.1:岗位角色(功能权限即角色及用户功能);4.2:界面设计(用例中详细介绍);4.3:功能视图(功能模块整体视图);4.4:功能清单(业务所需功能即增删查改等);4.5:用例:系统功能(增删查改)详细说明;
5、非功能规格:系统性能、可靠性、可用性、扩展性、安全性等;
6、附录:业务信息清单(功能模块涉及的对象属性信息)。
三、详细设计:
1、角色权限:角色定义及权限设计
2、总体设计:设计说明及功能结构
3、功能设计:每个模块功能的详细设计说明;
4、数据库设计:数据库实体关系及实体表信息。
更多相关内容 -
软件设计文档模板大全
2018-03-22 14:55:27该文档包含了操作手册、测试分析报告、测试计划、概要设计文档、开发进度月报、可行性研究报告、模块开发、软件需求说明书、数据库设计说明书、数据要求说明书、详细设计说明书、项目开发计划等文档模板 -
软件设计文档
2015-11-23 11:44:09软件设计的不同模型:瀑布式、快速原型法以及迭代式 自从1968年提出“软件工程”概念以来,软件开发领域对于借鉴传统工程的原则、方法,以提高质量、降低成本的探索就从未停止过。而在这个过程中,提出了许多不同的...软件设计的不同模型:瀑布式、快速原型法以及迭代式
自从1968年提出“软件工程”概念以来,软件开发领域对于借鉴传统工程的原则、方法,以提高质量、降低成本的探索就从未停止过。而在这个过程中,提出了许多不同的软件开发模型,典型的有:瀑布式,快速原型法,以及迭代式开发等。
- 瀑布式模型
是由W.W.Royce在1970年最初提出的软件开发模型,在瀑布模型中,开发被认为是按照需求分析,设计,实现,测试 (确认), 集成,和维护顺序的进行。
- 快速原型法
快速原型模型的第一步是建造一个快速原型,实现客户或未来的用户与系统的交互,用户或客户对原型进行评价,进一步细化待开发软件的需求。通过逐步调整原型使其满足客户的要求,开发人员可以确定客户的真正需求是什么;第二步则在第一步的基础上开发客户满意的软件产品。 - 迭代式开发
在迭代式开发方法中,整个开发工作被组织为一系列的短小的、固定长度(如3周)的小项目,被称为一系列的迭代。每一次迭代都包括了需求分析、设计、实现与测试。采用这种方法,开发工作可以在需求被完整地确定之前启动,并在一次迭代中完成系统的一部分功能或业务逻辑的开发工作。再通过客户的反馈来细化需求,并开始新一轮的迭代。
不同的开发模型,对于设计阶段的工作要求也不尽相同。相对来说,瀑布式模型中对于设计文档的粒度要求得最细,而快速原型法对于设计的要求一般来说比较弱,迭代式开发在每一阶段中的设计文档工作量都相对较少,但在软件开发完成后,最终的设计文档完善程度要比快速原型法的好。
软件设计的总体思路
软件设计的本质就是针对软件的需求,建立模型,通过将模型映射为软件,来解决实际问题。因此软件设计需要解决的核心问题是建立合适的模型,使得能够开发出满足用户需求的软件产品,并具有以下特性:
- 灵活性(Flexibility)
- 有效性(Efficiency)
- 可靠性(Reliability)
- 可理解性(Understandability)
- 维护性(Maintainability)
- 重用性(Reuse-ability)
- 适应性(Adaptability)
- 可移植性(Portability)
- 可追踪性(Traceability)
- 互操作性(Interoperability)
因此,软件设计并没有一套放之四海而皆准的方法和模板,需要我们的设计开发人员在软件的设计开发过程中针对软件项目的特点进行沟通和协调,整理出对软件项目团队的行之有效的方式,进行软件的设计。并保障软件设计文档的一致性,完整性和可理解性。
谁来进行软件设计
在我们开发人员中,有很多人这样理解:“软件设计文档就是软件架构师和设计人员的事情”,其实不然。设计文档是整个软件开发团队的产出,其中有些设计文档由架构师或者设计人员给出,有些文档由开发人员给出。这并没有一定的区分。
最佳实践
我们经常听到这样的话:
- “设计文档没有用,是用来糊弄客户和管理层的文档”;
- “用来写设计文档的时间,我的开发早就做完了”;
- “项目紧张,没有时间做设计”;
这些言论,并不是正确的观念,根据软件项目的实际情况,软件开发设计团队可以约定设计文档的详细程度。项目团队需要保障设计文档的完整性和一致性,在项目进度紧张的情况下,软件设计文档可以更初略一些;在项目时间充裕的情况下,相关文档可以更为详尽。但是在项目开发过程中,需要软件设计开发团队对于设计文档有共同的理解。
设计文档分类与使用
通常来说,作为软件项目,我们需要有这几类文档
- 需求说明文档
- 功能设计文档
- 系统架构说明书
- 模块概要设计文档
- 模块详细设计文档
就像我之前说到的,在某个软件团队,对于以上的文档的要求是可以完全不同的,在简单项目中,可能所有类型的文档放在一个文档中进行说明;在复杂项目中,每一类文档可能都要写几个文档;而在最极端的情况下,可能每一类文档都能装订成几册。因此,在我们软件设计和开发人员心目中需要明确的是:文档并不是我们进行设计的目标,也不是我们设计过程中额外的工作。
软件设计文档是我们在软件设计开发过程中形成的,用来在软件设计开发团队内部以及与各干系人之间进行沟通的文档,这些文档记录了软件项目中的各种知识,方案的思路、以及各种决策意见。 下面我们就软件设计开发过程中必须要完成的工作进行梳理,而我们需要注意到,这些需要完成的工作,在不同的开发流程模型的指导下可能有不同的时间要求,而我们需要关注的是在这个阶段内需要完成的工作,以及这个阶段内我们需要沟通的人员。
需求分析
需求分析是我们进行任何一个软件项目设计开发过程中都必须要完成的工作。
这个工作通常与客户一起完成。在不同的项目中,这个“客户”可能来自真正的购买产品的用户,使用系统的用户,也有可能来自团队的某个人员,如产品经理等。软件设计开发团队的参与成员根据项目的不同规模,则参与的人员也有所不同。原则上,设计开发人员参与的时间点越早,对于需求的理解和把握会更好。这个阶段,通常需要软件架构师参与其中。从资源优化的角度来说,开发人员不必参与需求分析,但需要理解需求。
需求分析的结果通常我们需要使用需求说明文档来描述,目前主流的需求描述方法包括:用户例图、用户故事等方式。这些方式有所不同的侧重,其核心思想就是描述清楚用户的使用场景。但无论采取何种方式,进行需求的描述,需求说明需要明确以下几点:
- 所需要开发的软件系统边界
- 系统所有的相关及使用人员角色
- 系统关键的使用场景
- 系统规模、性能要求以及部署方式等非功能性需求
功能设计
功能设计与需求分析差不多同时在开展,在很多软件项目中,对于功能设计不是特别重视。但对于某些软件项目而言,这是一个相当重要的工作。对于主要是用户界面的软件项目来说,功能设计可以看作是画出原型界面,描述使用场景,获得用户认可的过程。而对于没有界面的软件项目来说,则功能设计与需求分析的区分更为模糊。
参与的人员与需求分析的参与人员类似,架构师更侧重于参与此类工作,并给与一些实现层面的判断和取舍。
功能设计需要明确的核心是:
- 系统的行为
系统架构设计
系统架构设计是一个非常依赖于经验的设计过程。需要根据软件项目的特定功能需求和非功能性需求进行取舍,最终获得一个满足各方要求的系统架构。系统架构的不同,将很大程度上决定系统开发和维护是否能够较为容易的适应需求变化,以及适应业务规模扩张。
架构设计工作中,用户参与程度很低。软件开发团队中的需求人员参与程度很低,但团队中的所有核心设计和开发人员都应该参与其中,并达成一致意见。
架构设计的主要成果,是将系统的不同视图予以呈现,并使之落实到开发中:
- 系统开发视图及技术路线选择
- 系统逻辑视图
- 系统部署视图
- 系统模块视图
- 系统的领域模型
在软件开发过程中,系统的架构不是一成不变的,随着设计人员和开发人员对于系统的理解不断深入,系统的架构也会发生演化。在软件项目中,架构设计是开发团队沟通的统一语言,设计文档必须要随着系统的变化进行更新,保障开发团队对于系统的理解和沟通的一致性。
模块/子系统概要设计
模块/子系统的概要设计,由架构师参与,核心设计和开发人员负责的方式进行。
在概要设计工作中,我们需要在架构确定的开发路线的指导下,完成模块功能实现的关键设计工作。在概要设计阶段,需要关注于模块的核心功能和难点进行设计。这个过程中更多推荐的采用UML来进行概要设计,需要进行:- 模块实现机制设计
- 模块接口设计
- 关键类设计
- 画出时序图
- 交互图等。
模块详细设计
在瀑布式开发模型中,模块的详细设计会要求比较严格,将所有类进行详细设计。据我所知,除了一些对于系统健壮性要求非常严格的软件项目,如国防项目,金融项目还要求有详细设计文档之外。其他的项目大多采用其他方式来处理这样的工作,如自动化测试等。
综上所述,软件设计文档作为软件开发团队的沟通、理解、知识共享的手段,具有非常重要的意义。而根据软件团队的规模,对于文档上承载的信息详细程度可以有不同程度的要求。我们软件团队对于*如何使用设计文档有一个统一的理解,并坚持更新设计文档*,这就是软件设计的最佳实践!
软件设计所需要的知识与技能
- UML 统一建模语言
- 软件工程
- 面向对象的编程 OOP
- 操作系统
- 数据库原理
- 设计模式
- 沟通能力
-
软件设计文档编写概述
2018-04-19 22:08:24软件设计的三种模型:瀑布式、快速原型法以及迭代式自从1968年提出“软件工程”概念以来,软件开发领域对于借鉴传统工程的原则、方法,以提高质量、降低成本的探索就从未停止过。而在这个过程中,提出了许多不同的...软件设计的三种模型:
瀑布式、快速原型法以及迭代式
自从1968年提出“软件工程”概念以来,软件开发领域对于借鉴传统工程的原则、方法,以提高质量、降低成本的探索就从未停止过。而在这个过程中,提出了许多不同的软件开发模型,典型的有:瀑布式,快速原型法以及迭代式开发。瀑布式模型
是由W.W.Royce在1970年最初提出的软件开发模型,在瀑布模型中,开发被认为是按照需求分析,设计,实现,测试 (确认), 集成和维护的顺序的进行。
快速原型法
快速原型模型的第一步是建造快速原型,实现客户或未来的用户与系统的交互,用户或客户对原型进行评价,进一步细化待开发软件的需求。通过逐步调整原型使其满足客户的要求,开发人员可以确定客户的真正需求是什么;第二步则在第一步的基础上开发客户满意的软件产品。
迭代式开发
在迭代式开发方法中,整个开发工作被组织为一系列的短小的、固定长度(如2周)的小项目,被称为一系列的迭代。每一次迭代都包括了需求分析、设计、实现与测试。采用这种方法,开发工作可以在需求被完整地确定之前启动,并在一次迭代中完成系统的一部分功能或业务逻辑的开发工作。再通过客户的反馈来细化需求,并开始新一轮的迭代。
不同的开发模型,对于设计阶段的工作要求也不尽相同。相对来说,瀑布式模型中对于设计文档的粒度要求得最细,而快速原型法对于设计要求比较弱,迭代式开发在每一阶段中的设计文档工作量都相对较少,但在软件开发完成后,最终的设计文档完善程度要比快速原型法的好。
软件设计总体思路
软件设计的本质就是针对软件的需求,建立模型,通过将模型映射为软件,来解决实际问题。因此软件设计需要解决的核心问题是建立合适的模型,使得能够开发出满足用户需求的软件产品,并具有以下特性:
- 灵活性(Flexibility)
- 有效性(Efficiency)
- 可靠性(Reliability)
- 可理解性(Understandability)
- 维护性(Maintainability)
- 重用性(Reuse-ability)
- 适应性(Adaptability)
- 可移植性(Portability)
- 可追踪性(Traceability)
- 互操作性(Interoperability)
因此,软件设计并没有一套放之四海而皆准的方法和模板,需要我们的设计开发人员在软件的设计开发过程中针对软件项目的特点进行沟通和协调,整理出对软件项目团队的行之有效的方式,进行软件的设计。并保障软件设计文档的一致性,完整性和可理解性。
谁来进行软件设计
在我们开发人员中,有很多人这样理解:“软件设计文档就是软件架构师和设计人员的事情”,其实不然。设计文档是整个软件开发团队的产出,其中有些设计文档由架构师或者设计人员给出,有些文档由开发人员给出。这并没有一定的区分。
最佳实践
我们经常听到这样的话:
“设计文档没有用,是用来糊弄客户和管理层的文档”;
“用来写设计文档的时间,我的开发早就做完了”;
“项目紧张,没有时间做设计”;这些言论当然不正确。根据软件项目的实际情况,软件开发设计团队可以约定设计文档的详细程度。项目团队需要保障设计文档的完整性和一致性,在项目进度紧张的情况下,软件设计文档可以粗略一些;在项目时间充裕的情况下,相关文档可以更为详尽。但是在项目开发过程中,需要软件设计开发团队对于设计文档有共同的理解。
设计文档分类与使用
通常来说,作为软件项目,我们需要有这几类文档
- 需求说明文档
- 功能设计文档
- 系统架构说明书
- 模块概要设计文档
- 模块详细设计文档
就像之前说的,在不同的软件团队,对于以上的文档的要求是可以完全不同的,在简单项目中,可能所有类型的文档放在一个文档中进行说明;在复杂项目中,每一类文档可能都要写几个文档;而在最极端的情况下,可能每一类文档都能装订成几册。因此,在我们软件设计和开发人员心目中需要明确的是:文档并不是我们进行设计的目标,也不是我们设计过程中额外的工作。
软件设计文档是我们在软件设计开发过程中形成的,用来在软件设计开发团队内部以及与各干系人之间进行沟通的文档,记录了软件项目中的各种知识,方案的思路、以及各种决策意见。
下面我们就软件设计开发过程中必须要完成的工作进行梳理,而我们需要注意到,这些需要完成的工作,在不同的开发流程模型的指导下可能有不同的时间要求,而我们需要关注的是在这个阶段内需要完成的工作,以及这个阶段内我们需要沟通的人员。
需求分析
需求分析是我们进行任何一个软件项目设计开发过程中都必须要完成的工作。
这个工作通常与客户一起完成。在不同的项目中,这个“客户”可能来自真正的购买产品的用户,使用系统的用户,也有可能来自团队的某个人员,如产品经理等。软件设计开发团队的参与成员根据项目的不同规模,则参与的人员也有所不同。原则上,设计开发人员参与的时间点越早,对于需求的理解和把握会更好。这个阶段,通常需要软件架构师参与其中。从资源优化的角度来说,开发人员不必参与需求分析,但需要理解需求。需求分析的结果通常我们需要使用需求说明文档来描述,目前主流的需求描述方法包括:用户例图、用户故事等方式。这些方式不同的侧重点,其核心思想就是描述清楚用户的使用场景。但无论采取何种方式,进行需求的描述,需求说明需要明确以下几点:
1.所需要开发的软件系统边界
2.系统所有的相关及使用人员角色
3.系统关键的使用场景
4.系统规模、性能要求以及部署方式等非功能性需求功能设计
功能设计与需求分析差不多同时在开展,在很多软件项目中,对于功能设计不是特别重视。
但对于某些软件项目而言,这是一个相当重要的工作。
1.对于主要是用户界面的软件项目来说,功能设计可以看作是画出原型界面,描述使用场景,获得用户认可的过程。
2.对于没有界面的软件项目来说,则功能设计与需求分析的区分比较模糊。
参与的人员与需求分析的参与人员类似,架构师更侧重于参与此类工作,并给与一些实现层面的判断和取舍。
功能设计需要明确的核心是 系统的行为系统架构设计
系统架构设计是一个非常依赖于经验的设计过程。需要根据软件项目的特定功能需求和非功能性需求进行取舍,最终获得一个满足各方要求的系统架构。系统架构的不同,将很大程度上决定系统开发和维护是否能够较为容易的适应需求变化,以及适应业务规模扩张。
架构设计工作中,用户参与程度很低。软件开发团队中的需求人员参与程度很低,但团队中的所有核心设计和开发人员都应该参与其中,并达成一致意见。
架构设计的主要成果,是将系统的不同视图予以呈现,并使之落实到开发中:- 系统开发视图及技术路线选择
- 系统逻辑视图
- 系统部署视图
- 系统模块视图
- 系统的领域模型
在软件开发过程中,系统的架构不是一成不变的,随着设计人员和开发人员对于系统的理解不断深入,系统的架构也会发生演化。在软件项目中,架构设计是开发团队沟通的统一语言,设计文档必须要随着系统的变化进行更新,保障开发团队对于系统的理解和沟通的一致性。
模块/子系统概要设计
模块/子系统的概要设计,由架构师参与,核心设计开发人员负责的方式进行。
在概要设计工作中,我们需要在架构确定的开发路线的指导下,完成模块功能实现的设计工作。
在概要设计阶段,需要关注于模块的核心功能和难点进行设计。
推荐采用UML来进行概要设计,需要进行的工作如下:- 模块实现机制设计
- 模块接口设计
- 关键类设计
- 画出时序图
- 交互图等。
模块详细设计
在瀑布式开发模型中,模块的详细设计会要求比较严格,将所有类进行详细设计。
但现在除了一些对于系统健壮性要求非常严格的软件项目,如国防项目,金融项目要求有详细设计文档之外,其他项目大多采用其他方式来处理这样的工作,如自动化测试等。总结
软件设计文档作为软件开发团队的沟通、理解、知识共享的手段,具有非常重要的意义。
而根据软件团队的规模,对于文档上承载的信息详细程度可以有不同程度的要求。软件团队对于如何使用设计文档有统一的理解,并坚持更新设计文档,才是软件设计的最佳实践!
附录:
软件设计所需要的知识与技能
- UML 统一建模语言
- 软件工程
- 面向对象的编程 OOP
- 操作系统
- 数据库原理
- 设计模式
- 沟通能力
-
软件设计文档的写法
2012-10-18 20:40:13介绍软件设计文档怎么写 包括测试文档的写法 -
软件开发文档范例
2018-11-05 22:01:34软件开发文档中包括:测试分析报告、测试计划、程序维护手册、概要设计说明书、可行性报告、相机设计说明书、项目开发计划、需求分析说明书、用户操作手册、总结性报告等,以及类库开发设计规范。 -
如何编写一个好的软件设计文档——Medium中文站
2019-01-31 11:46:48作为一名软件工程师,我花了很多时间阅读和编写设计文档。在完成了数百篇这些文档之后,我亲眼目睹了优秀设计文档与项目最终成功之间的强烈关联。 本文试图描述使设计文档变得更好的原因。 本文分为4个部分: 为...作为一名软件工程师,我花了很多时间阅读和编写设计文档。在完成了数百篇这些文档之后,我亲眼目睹了优秀设计文档与项目最终成功之间的强烈关联。
本文试图描述使设计文档变得更好的原因。
本文分为4个部分:
- 为什么要写一份设计文件
- 什么在设计文档,包括
- 怎么写
- 围绕它的过程
为什么要写一个设计文件?
设计文档 - 也称为技术规范 - 描述了您计划如何解决问题。
关于为什么在进入编码之前编写设计文档很重要的原因已经有很多文章。所以我在这里说的是:
设计文档是确保正确工作完成的最有用工具。
设计文档的主要目标是通过强迫您思考设计并收集其他人的反馈来提高您的效率。人们通常认为设计文档的目的是教会其他人关于某个系统或稍后作为文档。虽然这些可能是有益的副作用,但它们本身并不是目标。
作为一般的经验法则,如果您正在处理可能需要1个工程师月或更长时间的项目,那么您应该编写设计文档。但不要止步于此 - 许多小型项目也可以从迷你设计文档中受益。
大!如果您还在阅读,您会相信设计文档的重要性。但是,不同的工程团队,甚至同一团队的工程师,经常以不同的方式编写设计文档。让我们来谈谈优秀设计文档的内容,风格和流程。
照片来自Todd Quackenbush的 Unsplash
在设计文档中包含哪些内容?
设计文档描述了问题的解决方案。由于每个问题的性质不同,您自然希望以不同的方式构建您的设计文档。
首先,以下是您应该至少考虑 在下一个设计文档中包含的部分列表:
标题和人物
您的设计文档的标题, 作者(应该与计划参与此项目的人员列表相同),文档的审阅者(我们将在“处理”部分中详细讨论)下面),以及本文档最后更新的日期。
概观
高级摘要,公司的每位工程师都应该理解并使用它来决定是否有必要阅读其余的文档。最多应为3段。
上下文
对手头问题的描述,为什么这个项目是必要的,人们需要知道什么来评估这个项目,以及它如何适应技术战略,产品战略或团队的季度目标。
目标和非目标
目标部分应:
- 描述项目的用户驱动影响 - 您的用户可能是另一个工程团队甚至是另一个技术系统
- 指定如何使用指标衡量成功 - 如果您可以链接到跟踪这些指标的仪表板,则可以获得奖励积分
非目标对于描述您不会修复哪些问题同样重要,因此每个人都在同一页面上。
里程碑
一个可衡量的检查点列表,因此您的PM和您的经理的经理可以浏览它并大致了解项目的不同部分何时完成。如果项目超过1个月,我建议您将项目分解为面向用户的主要里程碑。
使用日历日期,以便考虑无关的延迟,假期,会议等。它应该看起来像这样:
Start Date: June 7, 2018
Milestone 1 — New system MVP running in dark-mode: June 28, 2018
Milestone 2 - Retire old system: July 4th, 2018
End Date: Add feature X, Y, Z to new system: July 14th, 2018[Update]
如果其中一些里程碑的ETA发生变化,请在此处添加一个小节,以便利益相关者可以轻松查看最新的估算值。现有解决方案
除了描述当前的实现之外,您还应该通过一个高级示例流来说明用户如何与此系统交互和/或数据如何通过它。
一个用户故事是这个框架的好方法。请记住,您的系统可能包含具有不同用例的不同类型的用户。
提出的解决方案
有些人称之为技术架构部分。再次,尝试通过用户故事来具体化这一点。随意包含许多子部分和图表。
首先提供一个大的图片,然后填写大量 的 细节。瞄准一个你可以写这个的世界,然后在一个荒岛上度假,团队中的另一位工程师可以阅读它并按照你的描述实施解决方案。
替代方案
在提出上述解决方案时,您还考虑了什么?替代品的优点和缺点是什么?您是否考虑购买第三方解决方案 - 或使用开源解决方案 - 解决此问题而不是构建自己的问题?
可测试性,监控和警报
我喜欢包括这一部分,因为人们经常把它视为事后的想法或者一起跳过它们,而且当事情破裂并且他们不知道如何或为什么时,它几乎总会回来咬它们。
跨团队影响力
如何增加电话和开发负担?
它需要多少钱?
它是否会导致系统出现任何延迟回归?
它是否暴露了任何安全漏洞?
有什么负面后果和副作用?
支持团队如何与客户沟通?打开问题
任何你不确定的未解决的问题,你想让读者权衡的有争议的决定,建议未来的工作,等等。这部分的一个诙谐的名字是“已知的未知数”。
详细的范围和时间表
本节主要是由参与该项目的工程师,他们的技术主管和他们的经理阅读。因此,本节在文档的最后。
从本质上讲,这是您计划执行项目的每个部分的方式和时间的细分。有很多内容可以准确地确定范围,因此您可以阅读此文章以了解有关范围界定的更多信息。
我倾向于将设计文档的这一部分视为正在进行的项目任务跟踪器,因此每当我的范围估计发生变化时,我都会对此进行更新。但这更多的是个人偏好。
怎么写
现在,我们已经谈了什么进入一个好的设计文档,让我们来谈谈写作风格。我保证这与你的高中英语课不同。
写得尽可能简单
不要试着像你读过的学术论文那样写作。它们是为了给期刊评论家留下深刻印象。您的文档是为了描述您的解决方案并从您的队友那里获得反馈而编写的。您可以通过以下方式实现清晰:
- 简单的话
- 短句
- 项目符号列表和/或编号列表
- 具体的例子,如“用户爱丽丝连接她的银行帐户,然后......”
添加大量图表和图表
图表通常可用于比较几个可能的选项,图表通常比文本更容易解析。我已经用Google Drawing创建图表了。
专业提示:请记住在屏幕截图下添加指向图表的可编辑版本的链接,以便您可以在以后不可避免地发生变化时轻松更新。
包括 数字
问题的规模通常决定了解决方案。为了帮助审阅者了解世界状况,请包括实际数字,例如数据库行数,用户错误数,延迟数以及这些数据如何随着使用情况而扩展。还记得你的Big-O符号吗?
试着变得有趣
规范不是学术论文。此外,人们喜欢阅读有趣的东西,所以这是让读者保持参与的好方法。尽管如此,不要过分夸大核心思想。
如果你和我一样,很难搞笑,Joel Spolsky(显然以他的喜剧天赋而闻名......)有这样的提示:
有趣的最简单的方法之一就是在没有被 要求时 具体说明 [......例子:]而不是说“特殊利益”,而是说“左撇子avacado农民”。
进行怀疑测试
在将您的设计文档发送给其他人进行审核之前,请假装成为审核人员。您对此设计有什么疑问和疑问?然后先发制人地解决它们。
做假期测试
如果您现在无法访问互联网,那么您团队中的某个人是否可以阅读该文档并按照您的意图实施该文档?
设计文档的主要目标不是知识共享,但这是一种评估清晰度的好方法,以便其他人可以实际为您提供有用的反馈。
处理
啊,是可怕的P字。设计文档可帮助您在浪费大量时间实施错误解决方案或解决错误问题之前获得反馈。获得良好反馈有很多艺术,但这是后来的文章。现在,让我们专门讨论如何编写设计文档并获取反馈。
首先,参与项目的每个人都应该参与设计过程。如果技术主管最终决定做出很多决定,那也没关系,但是每个人都应该参与讨论并购买设计。因此,本文中的“你”是一个真正的复数“你”,其中包括项目中的所有人。
其次,设计过程并不意味着你盯着白板理论化的想法。随意将您的手弄脏并制作潜在的解决方案原型。这与在编写设计文档之前开始为项目编写生产代码不同。不要那样做。但你绝对应该随意写一些hacky一次性代码来验证一个想法。为了确保您只编写探索性代码,请将此原型代码中的任何一个都合并为master。
之后,当您开始了解如何进行项目时,请执行以下操作:
- 请您团队中经验丰富的工程师或技术负责人成为您的评审员。理想情况下,这将是一个受到良好尊重和/或熟悉问题边缘情况的人。如有必要,用boba贿赂他们。
- 进入带白板的会议室。
- 描述你正在向这位工程师解决的问题(这是非常重要的一步,不要跳过它!)。
- 然后解释你想到的实现,并说服他们这是正确的构建。
在开始编写设计文档之前完成所有这些操作可以让您在投入更多时间并接受任何特定解决方案之前尽快获得反馈。通常情况下,即使实施保持不变,您的审核人员也可以指出您需要覆盖的极端案例,指出任何可能的混淆区域,并预测您以后可能遇到的困难。
然后,在您撰写了设计文档的粗略草稿后,让相同的审阅者再次阅读,并通过在设计文档的“ 标题和人物”部分中添加他们的名称作为审阅者来标记它。这为审阅者创造了额外的激励和责任。
在这方面,考虑为设计的特定方面添加专门的审阅者(例如SRE和安全工程师)。
一旦您和审核人员签字,请随时将设计文档发送给您的团队,以获得更多反馈和知识共享。我建议将反馈收集过程限时约1周,以避免延误。致力于解决人们在该周内留下的所有问题和评论。留下评论悬挂=坏业力。
最后,如果您,您的审阅者和其他阅读该文档的工程师之间存在很多争议,我强烈建议您在文档的“ 讨论”部分中合并所有争用点。然后,与各方召开会议,亲自谈论这些分歧。
每当讨论主题长度超过5条评论时,转向亲自讨论往往会更有效率。请记住,即使每个人都无法达成共识,您仍然有责任进行最后的通话。
在最近与Shrey Banga谈论此事时,我了解到Quip有一个类似的过程,除了作为审阅者在您的团队中拥有经验丰富的工程师或技术负责人之外,他们还建议让不同团队的工程师审核该文档。我没有试过这个,但我当然可以看到这有助于从不同角度的人那里获得反馈,并提高文档的一般可读性。
完成上述所有操作后,即可开始实施!对于额外的布朗尼点,在实施设计时将此设计文档视为活文档。每当您了解到导致您更改原始解决方案或更新范围的内容时,请更新文档。如果您不必一遍又一遍地向所有利益相关者解释,您会感谢我。
最后,让我们真正了解一下:我们如何评估设计文档的成功?
我的同事Kent Rakip对此有一个很好的答案:如果完成正确的投资回报率,设计文档就会成功。这意味着成功的设计文档实际上可能导致这样的结果:
- 您花了5天时间编写设计文档,这迫使您通过技术架构的不同部分进行思考
- 您可以从审阅者那里获得反馈,这
X
是建议架构中最具风险的部分 - 您决定先实施
X
以降低项目风险 - 3天后,你发现这
X
是不可能的,或者比你原先预期的要困难得多 - 您决定停止处理此项目并优先考虑其他工作
在本文开头,我们说设计文档的目标是确保正确的工作完成。在上面的示例中,由于这个设计文档,您可能只花了8天时间,而不是浪费可能几个月才能中止此项目。对我来说似乎是一个非常成功的结果。
如果您有任何问题或反馈,请在下面留言!我也很想知道你如何在团队中以不同的方式设计文档。
-
软件架构设计文档,模板.doc
2020-03-10 18:34:48软件架构模板,专门用于评审。 -
软件开发文档模板(全套)
2018-05-18 11:42:451、可行性研究报告 ...4、概要设计说明书 5、详细设计说明书 6、用户操作手册 7、测试计划 8、测试分析报告 9、开发进度月报 10、项目开发总结报告 11、程序维护手册 12、软件问题报告 13、软件修改报告 -
软件功能详细设计文档(示范).doc
2019-06-19 09:16:28针对软件开发人员得开发功能设计文档,让程序员了解功能设计文档包含得内容。 -
软件设计文档国家标准_GB8567--88
2017-04-20 17:30:47这些是软件设计工作的重要约束 2.3 假定和约束 列出进行本软件开发工作的假定和约束,例如经费限制、开发期限等。 3 需求规定 3.1 对功能的规定 用列表的方式(例如IPO表即输入、处理、输出表的形式),逐项定量和... -
(软件开发)功能设计文档.doc
2019-06-19 09:26:09帮助程序员快速了解设计文档中需要得内容,概况及目录格式等 -
软件设计文档锦集(模板)
2009-11-13 19:55:10软件设计文档锦集(模板)软件设计文档锦集(模板)软件设计文档锦集(模板)软件设计文档锦集(模板)软件设计文档锦集(模板)软件设计文档锦集(模板) -
软件详细设计文档模板
2012-04-18 14:45:44软件开发文档是软件开发使用和维护中的必备资料。它能提高软件开发的效率,保证软件的质量,而且在软件的使用过程中有指导,帮助,解惑的作用,尤其在维护工作中,文档是不可或缺的资料 -
软件开发功能设计文档(示范参考).doc
2019-06-19 09:21:47记录了软件开发 人员在写文档时,需要展现得内容概况,条理清晰写出好文档。 -
如何写好一份软件开发设计文档
2021-10-21 16:06:06设计文档- 也被称作技术规范和实现手册,描述了你如何去解决一个问题,是确保正确完成工作最有用的工具,其目的是迫使你对设计展开缜密的思考,并收集他人的反馈,进而完善你的想法,同时在软件交付和交接的过程中,... -
软件系统详细设计文档模板(超级正规).doc
2019-07-18 11:43:17XXX软件详细设计说明书 1 Revision Record 修订记录 2 1 引言 3 1.1 编写目的 3 1.2 背景 4 1.3 参考资料 4 1.4 术语定义及说明 4 2 设计概述 4 2.1 任务和目标 4 2.1.1 需求概述 4 2.1.2 运行环境概述 4 2.1.3 条件... -
华为软件概要设计模板.doc
2019-08-12 11:18:26华为软件概要设计文档,提供给需要编写规范软件设计文档的同学。 -
软件开发概要设计文档
2018-11-30 09:15:57基于电商平台的软件开发概要设计文档,主要提供概要设计的模板设计,内容包含了各种er图,时序图,流程图,数据库设计图等内容 -
软件系统详细设计文档模板
2019-07-19 13:59:50软件系统详细设计文档模板 -
如何写软件设计文档
2013-07-13 09:33:32软件设计的不同模型:瀑布式、快速原型法以及迭代式 自从1968年提出“软件工程”概念以来,软件开发领域对于借鉴传统工程的原则、方法,以提高质量、降低成本的探索就从未停止过。而在这个过程中,提出了许多不同的... -
接口设计说明书(软件设计文档范例)
2009-12-11 16:48:54接口设计说明书 本接口说明书详细介绍了LK9000编程接口函数的功能,用法、声明所在的头文件。用户在开发LK9000软件时必须阅读该说明书。 -
软件设计文档模板
2013-04-12 14:52:42包含5个文件,分别是:软件需求分析报告、软件概要设计报告文档、软件详细设计报告文档、软件数据库设计报告文档、软件测试大纲 -
软件开发文档-详细设计文档
2019-06-21 11:22:34帮助开发人员理解项目的业务逻辑术语描述执行标准与相关文档 编码标准,文件管理标准,版本管理标准项目概述 1.背景 2.现状项目目标编码规范系统功能概述 系统功能总图系统总体介绍系统模块设计 模块结构图,... -
软件开发详细设计文档模板
2016-05-11 11:31:09详细设计文档 -
《软件架构设计文档》模板
2011-12-23 08:58:37本文档是软件架构设计模板,虽然简单了些,但是希望可以帮助到需要的人 -
web项目详细设计文档
2015-10-09 11:47:37让初学web开发人员快速上手项目详细设计文档编写!