工程管理文档：概要设计说明书

2019-11-05

软件工程管理中，有几个比较重要的文档，软件开发者这边会接触到的，有：需求输入表、需求规格说明书，概要设计，详细设计，自测报告。这里我想要谈一谈概要设计文档，也是对于开发者而言，最重要的文档。其他文档及相关过程，另写文章总结。

一、谁负责？
谁负责这个问题一定要明确？我觉得这个问题很重要，非常重要。有些时候，项目的技术负责人会把概要设计交给属下每一个人负责一部分，然后收集并综合起来。我认为，这是不对的。一般来说，一个技术团队，技术leader 就是那个技术最厉害的人。概要设计文档应该由技术leader完全负责。如果是web或者mobileApp项目，可能开发团队不超过二十人，分成两三个、三四个小组，而且，大家的技术技能还比较类似。如果是算法软硬件结合项目，或CAD类型项目，可能涉及到三四十人，技能领域可能差别较大，一个小组的内容，其他的小组可能完全不会，或者花两年的时间学习也能够会。这就比较麻烦了。如我们之前的项目：虚拟制衣CAD项目：CAD组、渲染算法组、物理引擎组。这样子的项目，每个方向的难度较大，就需要小组长来辅助技术负责人做好概要设计。技术负责人不能把这些工作下放给普通开发者。我一向秉承拿最大份的酬劳，输出最大的价值，担最大份责任的原则。
为什么一定要技术负责人来做概要设计呢？找组员A过来，他是不是也能干了这个活儿呢？比如说，他手上拿着Scrum或者UML的教材，是不是也能照猫画虎呢？并不能，软件工程，与其他类型项目的工程也有类似之处，技术积累的年限是保证经验的简单的标准。经过长年的训练，一个领导人对于项目的各个环节都非常熟悉，虽然未必有每个环节的负责人熟悉，但是对于项目的把控肯定是行业经验所带来的较优水平。

二、有什么作用？
概要设计说明书是给开发团队使用的。对于小型项目，概要设计说明书可能不不重要，可有可无，代码中的注释即足够。对于中大型项目，由于开发周期长，人员变动多，靠口口相传是不够的。规范的、统一的概要设计文档才是保证代码实现正确的最大保证。软件工程实践里，我们对于术语的使用其实不是那么严谨的，对于组员沟通来讲，会带来一些歧义，所以，我们需要文档以及规范化流程来保证交流的顺畅。

三、要做什么？什么内容？
简单来说，就是指导每一个开发者如何开发项目。选择每个模块的实现方案，例如网络功能的模块，是选择基于libevent、libuv等等，还是自己实现，UI框架选择哪个，MVC模式应该如何实现，数据库选择。其二，模块之间的关系，通信方式，例如，有的人喜欢通过构建好model之后，喜欢通过id或者handle的方式在view、controller层使用，有人喜欢完全隔离的View/Controller端，在桌面端项目中模仿Web端的View/Controller层次，有人喜欢在桌面端软件采用前后端分离的方案，有的人不喜欢，既然是技术负责人做了最终的方案选择，就需要为自己的选择负起责任。因为技术方案的选择而代码的开发周期增加，不能把过错转移到普通组员身上。若选择合适的方案让预估开发周期变短，那是设计者的功劳。

百科对概要设计的定义为：

在该阶段，根据上一阶段的需求来确定总体的实现方案，确定整个软件的大体布局，各模块的功能以及模块之间的衔接，模块与外部系统的关系。在这个阶段，设计者会大致考虑并照顾模块的内部实现，但不过多纠缠于此。主要集中于划分模块、分配任务、定义调用关系。模块间的接口与传参在这个阶段要定得十分细致明确，应编写严谨的数据字典，避免后续设计产生不解或误解。概要设计一般不是一次就能做到位，而是反复地进行结构调整。典型的调整是合并功能重复的模块，或者进一步分解出可以复用的模块。在概要设计阶段，应最大限度地提取可以重用的模块，建立合理的结构体系，节省后续环节的工作量。

概要设计文档最重要的部分是 分层数据流图、结构图、数据字典以及相应的文字说明等。以概要设计文档为依据，各个模块的详细设计就可以并行展开了。

有的项目涉及到硬件部分，我们需要把视野放的更开一些，若硬件部分的工作不多，也需要把它囊括在内。所谓设计文档，是针对于整体过程而言，非仅软件代码部分。

在整个过程中，我们需要做如下图表绘制：
1，用例图
用例图（user case）应该在需求分析阶段绘制，落实到详细设计文档中。概要设计阶段，设计者应该熟悉了每一个用例，并细化至活动图。
2、组件图（component diagram组件是封装了可执行特定功能的单位。组件的类型包括了可执行文件、文档、数据库表格、文件和库文件等。一些开发者，把lib当作组件。其目标是软件就像垒积木一样，垒组件就能形成新的软件。然而，UML中组件的含义更加宽泛，这里会导致歧义，提一句。
3、class diagram
class diagram基本上是在详细设计阶段绘制的。没有详细设计的工作，如何能够做好class 层次，而且，在具体实现的时候，会发现，设计会做更改。若不打算写详细设计文档，可以绘制关键模块的class diagram。

4、模块关系图
概要设计过程，需要确定开发过程所用的过程方法（开发模型）。如XP、Scrum、瀑布等。从开始文档制作始，就定好了，且在执行了。如想要走瀑布模型，那么制作文档的过程就是独立的，连续一致的；如想要做敏捷过程的，可能概要设计完成了，就开始了编码，同步完善详细设计。

四、如何写？
我们需要找一份模板，认真的把每个步骤完成。对于文档的格式，其实没必要那么关注。大公司内部早就制作好适合自己的文档格式，中小公司在还没有形成自己的文档时，从互联网上找一些模板，综合一下就可以形成自己所需的格式。经过一两年的迭代，整个团队就会适应这个文档的流程。照猫画虎的填写完当然是不难的，难的是做出合理的设计。写出文档与写好文档是两回事。这里直接牵扯出了另外一个问题：如何评价？这个问题重要性不言而喻，谁有能力去评价一个技术负责人是否能力合格呢？到底如何去评估呢？我的评价标准很简单：在2.0的版本中，不会有组员强烈提出架构代码的重构。
概要分析是迭代着做的，不是花一周、两周做好了，不修改了，成为标准、规范了，如同”C++代码规范“。它会在我们进行详细设计的过程中反复被修改。软件工程中，建议设计阶段占时间1/4，设计者在足够长的时间内，应该把绝大多数难题都解决掉。但是，我们又不能无限期修改下去，需要明确时间点。所以，leader与各组长完成初步的详细设计之后，进行第一次修改。各组长与组员进行详细设计，较长时间后，组长修改模块设计，与leader 共同确定第二次修改。总共三版。在程序开始开发代码之前，应该封存。

此过程中，大概会提出一些问题：
1，设计中明确需要一个模块，但是，在没有详细设计之前，甚至是没有开发时，我们并不确定，这个模块是否满足预期的性能、功能要求。有可能做出来才能明确，该方案不满足需求，该功能无法实现。
  对于这种问题，真的是毫无办法，因为，已经超出了知识范围。只能请教更高级的专家。
2，为什么我只写了一种方案，并没有多种可选方案？
  因为，已经把可选项排除了。我们可以备选方案也加上，首选方案的某些问题可能未被发现，一旦发现，首选方案可能也变成了备选方案。
3，若在一个老的项目上，重新实现第二版，那么，我们会觉得，概要设计这个过程中，并没有做什么事情，总感觉心里不踏实，怎么办？
   不用担心，本来就是如此，在之前的版本里，需求、概要、详细分析，都作过。新版本的设计中，只需要继续优化就好了。

P.S. 这篇总结我放了好久哦，躺两年了吧。今年者的是懈怠了。终于把结婚这个任务完成了，也在这个城市安家了，人生正式进入新的阶段。对于做技术的道路，这两年我也有的新的认知，希望能走上不一样的道路吧。
P.P.S. 若需要各种文档模板，可留言。我稍后整理出来整套的模板供下载。

https://en.wikipedia.org/wiki/Systems_development_life_cycle
https://elf8848.iteye.com/blog/1582323

如果有任何意见，欢迎留言讨论。

[ 主页 ]

工程管理文档：概要设计说明书相关推荐

国际软件设计文档——概要设计说明书
1 引言 1.1 编写目的说明编写这份概要设计说明书的目的,指出预期的读者. 1.2 背景说明: 待开发软件系统的名称: 列出此项目的任务提出者.开发者.用户以及将运行该软件的计算站(中心). 1 ...
php列表显示教程,Dedecms后台管理文档列表显示自定义字段方法教程
有客户提出要求,在DEDECMS后台管理文档列表中,需要在列表中显示自定义的字段内容,在默认状态下,这些字段是不会再列表中显示的,下面就是解决方法: 找到dede/content_list.php文件 ...
Python工程的文档结构
Python工程的文档结构,可以参考https://stackoverflow.com/questions/193161/what-is-the-best-project-structure-for- ...
使用SharePoint 2010新增的文档集内容类型来管理文档
使用SharePoint 2010新增的文档集内容类型来管理文档 SharePoint 2010新增加的文档集功能是作为内容类型存在的,使用范围在网站集中,需要激活"文档集"功能到 ...
erp系统服务器都是维护些什么意思,erp系统维护服务器维护管理文档.doc
erp系统维护服务器维护管理文档 ERP系统机箱及服务器管理维护文档 page 4 ERP系统机箱及服务器管理维护文档作者:数据技术组创建日期:2013-05-08 修改日期: 版本:1.0 目录 ...
django 1.8 官方文档翻译：7-3 Django管理文档生成器
Django管理文档生成器 Django的admindocs应用从模型.视图.模板标签以及模板过滤器中,为任何INSTALLED_APPS中的应用获取文档.并且让文档可以在Django admin中使 ...
知识管理文档协同不一定要用语雀和石墨，用它效果更好
随着信息化建设和电子商务时代的到来,企业核心知识资产大多以电子文档的形式存在,保护这些电子文档就是保护企业核心竞争力. 企业知识库可以科学规范化的存储和管理企业的知识资产,换而言之要想提高企业的竞争力 ...
作为一个程序员，你是怎么管理文档资料的？我这个方法特别方便
看到这个问题我觉得可能有下面这些想法: A:什么文档资料,我没有整理的习惯. B:磁盘文件管理. C:用笔记软件它不香吗. D:自己搭建一个网站. 上面的这些情形我都经历了,最后我选择了gitee+t ...
如何做出有价值的知识管理文档？
知识管理文档是企业中重要的资产,它可以帮助企业员工更好地理解业务流程.产品功能.标准操作等信息.如何做出有价值的知识管理文档,满足员工知识需求,提高工作效率,本文将探讨以下几个方面: 一.制定有效的知 ...

工程管理文档：概要设计说明书

工程管理文档：概要设计说明书相关推荐

最新文章

热门文章