系统设计文档结构体例理解与决策

个人体会，在一个软件项目的实施过程中，三份文档最重要：需求文档、设计文档和测试方案。这三份文档做好了，对整个软件项目高质量、高效率地实施有很大促进作用，可以说事半功倍。三份文档之间是有联系的，需求确定边界，设计决定实现，测试检验实现。

以前做项目也写过文档，大型国家工程化项目，项目做完了文档堆成山，但都是凑数，而小型项目，时间紧张，文档一般都是用于衔接工作，来不及写齐备地文档，更别说规范，高质量。最近刚好有一个项目，可以试试文档规范化，让写出来的东西有价值，能真正指导实施。在写的过程中，渐渐发现，要写一份规范、高水平的软件实施工程文档也不是那么容易的，先不说内容、语言水平，首先一点文档内容结构的确定，就很费心思。文档结构没定好，就会导致需求泛泛，不能服务设计、设计像需求，测试没着落。这里把最近自己定设计文档的一些思路记下来，是否正确，则是大家仁者见仁了。

CMM3有一套完整的软件实施工程文档规范，当然要基于这个结构来定，下面是一个以前项目的基于按照CMM3来设计内容结构的文档例子：



总共8章，其中第8章也有很多直接放在第1章，写为文档概述。通过观察2、3级目录不难发现，这是一个结构相对复杂的系统，项目至少在百万级以上，因为一个系统包括多个子系统，所以在文章主体的第2、3、4、6章都是分子系统进行编写。

第1章系统总论不是必须，是根据项目实际情况来定的，有很多人直接放在第2章体系结构中，如果系统特别复杂，或者有必要对系统先做一个整体的、重要方面的概述，则作为单章，一般情况下是服务于评审。

第2章体系结构是重头戏，一般还会包括系统约束说明，本项目可能没有，省去此节。本章中逻辑视图和进程视图是非常考验设计功能的章节，逻辑视图主要对系统和模块（组件）之间的关系作出说明，而进程视图则要求将系统的进程、线程计划及交互流、生命周期阐述清楚，可通过图、表、文字综合说明。第三节是模块（组件）设计，模块是概设的主要内容，模块是面向结构化程序的说法，组件是面向对象程序的说法。模块一般大家都很熟悉，也是所有设计人员必须做的设计内容，就不用多说了。

第3章，数据设计，不仅仅包括数据库设计，系统涉及到的配置文件、模板文件、文件形式存储的数据组织设计都需要进行详细说明。如果系统是大数据库处理的系统，数据库设计就要单独写成本子，不能放在这儿写了。

第4章 系统组装与部署设计。本项目把接口设计放在了这一章，也有很多时候接口设计独立成章，或者跟模块设计放在一节，具体放在什么位置，要看接口在整个系统中占的比重，以及跟模块之间的关系紧密度。系统组装的设计做得好，那么后期的部署就简单多了，想一想，如果一个项目3个人开发，4个子系统，没有统一的组装设计，各人开发的系统都是独立的部署单元和部署配置方法，那么后期的部署人员就要一次部署至少8套以上程序，记忆8套配置方法，如果恰好这个项目是全国各省部署，那这个工作量就够吓人的人啦。系统组装与部署设计一定要考虑到部署配置的粒度，而不是简单地画出服务上的系统构成。

第5章的安全设计，本项目主要是针对等保写的，一般可以省略。

第6章界面设计，本项目的界面设计是写得非常好的，基本上各个子系统的各个页面全部覆盖，并且对各界面元素作了详细操作说明。一般情况下很难作到这种程度，一个项目的美工设计在概设时一般只定了大体的界面风格，出来几张典型界面。

第7章是写的概设与招标文件、需求的追溯关系，这个一般也是用于评审。