引言

经常听到调侃程序员的一句话”程序员最烦写文档,也最烦别人不写文档”。文档在项目开发中非常重要,首先是自己对产品和设计要非常熟悉才能写出一篇好的设计文档,其次文档可以让别人快速理解技术架构,快速上手。这里总结下自己这几年写概要设计文档的经验。

产品文档

产品文档虽然是产品经理编写,但是我们还是要去了解其中详细的信息,尤其是开发背景和整体原型。这样才能开发出符合产品设计的产品。

环境信息

记录开发及测试环境的数据库用户名/密码,部署的服务信息及服务部署的主机信息。生产环境的主机信息等。

技术架构

技术架构也可设计为整理模型,说明的是后台技术大的框架。

模块设计,可以写以下内容:

1、模块描述:说明哪些模块实现了哪些功能;

2、模块层次结构:可以使用某个视角的软件框架图来表达;

3、模块间的关系:模块间依赖关系的描述,通信机制描述;

4、模块的核心接口:说明模块传递的信息、信息的结构;

5、处理方式设计:说一些满足功能和性能的算法。

下面是个简单的例子:

整体流程图

描述的是整个流程时序图,当然可附带些描述性文字

ER图

实体-联系图,描述实体类型、属性和联系的方法。在表设计中也有体现。

时序图

描述请求详细流程的时序图。

数据表

将设计的数据库文档及语句记录下来。描述每个字段的含义,可包含字段、类型、Enum、描述、备注列,将设计的SQL文件上传,有更新时需及时更新。

缓存

将用到的缓存设计记录下来,无论是jvmCache还是中间件。

接口

前后端的接口文档,可链接到接口文档页面。

特殊点及疑问点

将有问题的点记录,后续解决。

迭代记录

记录每次迭代的新增功能或修改记录。