详设文档编写

今天老大要求开始写详设文档，具体到接口的逻辑，写了一天的详设文档，我来说说对此的看法。

为啥详设文档编写

1. 编写一个好的详设文档可以更好的了解该需求的逻辑处理
2. 编写一个好的详设文档可以更好的与前端、测试沟通，了解该逻辑是否有问题
3. 编写一个好的详设文档可以方便新同事快速熟悉项目逻辑
4. 编号一个好的详设文档可以了解程序的不足，方便后续优化
5. 编写一个好的详设文档可以了解各个版本的修改点

详设文档的各种形式以及优缺点

• 编写详设文档的好处太多了，那么既然详设文档的好处这么多，我们该如何编写详设文档呢？
• 详设文档的形式
  • 详设文档的形式有很多，比如:
    • 文档 : 以文字的形式描述该需求以及实现逻辑
    • 流程图：以流程化的形式描述该需求以及实现逻辑
• 优缺点
  • 文档
    • 优点：主要方便描述该需求的背景，开发人员，需求描述，接口的分配，细的逻辑方便书写
    • 缺点：在宏观描述需求难度较大，不够直观，不够简洁
  • 流程图
    • 优点：主要方便阅读需求的逻辑，前后端交互，清楚的了解需求从哪到哪
    • 缺点：没有足够的文字作为支撑，无法清楚了解该需求的背景，非常细的逻辑书写比较麻烦，没有文字来的方便

如何编写一个好的详设文档

• 流程图
  • 我们不需要把需求逻辑写的有多细，如果有细的地方，我们可以以文字的形式描述出来，这样更方便描述该逻辑。
  • 我们只需要把其大致逻辑书写，保证简洁即可
  • 我是后端开发，编写的文档是给测试、前端开发看的，因此对于后端开发来说，我们主要是给他们看具体的需求逻辑。那么编写的文档形式是以流程图为主的。
  • 如果有sql的逻辑，我们只需要把其大致逻辑描述并附上相关表写上，然后在另一个页面把其sql贴出来即可。
  • 如果有转换逻辑，我们可以在另外的页面描述其具体逻辑，在主体逻辑上稍微描述大致即可。
  • 流程图我们可以在一个页面描述其主体，具体详细逻辑放在其他页面上即可。
  • 我们在书写需求流程图时，我们可以使用垂直职能图来描述前端与后端，后端中各个组件之间的关系。
  • 从前端到后端到具体某个组件的流程就可以清晰的描述出来。
  • 具体的可以这么细分
    • 从各个系统之间的关联关系
    • 从前端到后端之间的物理流程图，比如：客户端请求->F5->服务器->数据库
    • 后端接口的流程图
    • 某类数据的流向
    • 等
• 文档
  • 文档规范（出自tableShip/详细设计文档编写规范）

## 一．引言 

### 1． 编写目的（阐明编写详细设计说明书的目的,指明读者对象。） 
### 2． 项目背景（应包括项目的来源和主管部门等。） 
### 3． 定义（列出文档中用到的专门术语定义和缩写词的原意。） 
### 4． 参考资料（列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：（1）项目的计划任务书,合同或批文；（2）项目开发计划；（3）需求规格说明书；（3）概要设计说明书；（4）测试计划(初稿)；（5）用户操作手册(初稿)；（5）文档所引用的其他资料、软件开发标准或规范。） 

## 二．总体设计 

### 1．需求概述 
### 2．软件结构（如给出软件系统的结果图。） 

## 三．程序描述（逐个模块给出以下的说明）
 
### 1．功能 
### 2．性能 
### 3．输入项目 
### 4．输出项目 
### 5．算法（模块所选用的算法。）
 
### 6．程序逻辑（详细描述模块实现的算法，可采用:：（1）标准流程图；（2）PDL语言；（3）N-S图；（4）PAD；（5）判定表等描述算法的图表。）
 
### 7．接口 
### 8．存储分配 
### 9．限制条件 
### 10． 测试要点（给出测试模块的主要测试要求）

以上就是我对于详设文档的一些理解，详设文档的好处很多，我们对其需要引起重视。