我们可能听过一句话，“程序员最头疼的就是编写开发文档，最头疼的也是没有开发文档”。开发文档对于开发来说像是代码使用说明书，没有开发文档是很难受的，想要写好开发文档也是不容易的。
开发文档是开发对开发目标进行设计到实现过程的总结性文档，可以帮助开发人员整理思路，评估开发结果，能为后续开发、扩展甚至重构提供指导性的参考，避免直接从代码重新理解开发思路，提高了后续开发效率。
开发文档有很多种，比如整个软件的开发文档、整个项目的开发文档、单项功能需求的开发文档等，不同的开发文档所关注的重点不同，编写的规范也不可相提并论。本文主要分析单项需求的开发文档编写思路。
谁来写，写给谁看
一般来说，开发文档由对应的开发人员撰写，开发文档关注的重点其实就是代码的实现逻辑，也只有开发人员自己最为清楚。
但是开发文档不只是写给自己看的，是要给所有开发甚至产品也能看懂得文档，不能仅仅是技术上的表述，更多应该抽象到逻辑层面的实现，代码的展示只是表现逻辑的辅助手段（代码本身也只是逻辑的表象）。
了解了谁来看的问题，我们就能知道写好开发文档需要关注的重点和细节是哪些。
关注点和细节
对于开发来说，我们编写的文档目的是让开发能：
- 快速了解某项功能的实现逻辑，对代码的执行流程有清晰地认识，以便于后续开发和功能扩展的逻辑调整
- 快速分析代码的问题所在，找到解决办法
- 为后续代码优化和代码评估做参考
- 为相似功能的聚合或者模仿做参考
对于产品而言，开发文档需要的关注点主要为：
- 需求的实现程度
- 需求的可扩展性
- 需求的实现逻辑合理性评估
综上来看，一份值得开发和产品查阅的开发文档需要重点关注：需求的分析、需求的实现逻辑、代码的可扩展性和使用细节、相关评估、需要特殊注意的问题、遇到的问题和难点。
一份目录
写一份什么样的开发文档取决于文档的具体用途，用途决定文档的侧重点不同，一份文档不可能面面俱到，也没有这种必要，文档在乎简洁准确，而不是繁复。虽然有使用说明书的特性，但不可篇章充斥细节，纠结于琐碎的事情，而需要把眼光放到整体性上，从全局的角度围绕需求和实现逻辑来整理文档。
以下是提供的一份参考目录（不要拘泥于此，你需要的可能完全不同，每份文档也不尽相同，重点在于你需要表达的东西）：
## 需求分析
+ 相关概念、属性介绍
+ 交互及界面
+ 实现的功能
+ 设计思路（用例图、流程图等加以辅助）
## 实现逻辑与细节
+ 涉及的文件及代码
+ 交互实现
+ 功能实现
+ 其他补充
## 扩展
+ 功能的扩展
+ 组件的使用
## 评估
+ 性能分析与优化
+ 和其他功能的关联
+ 遇到的问题和难点
+ 需要注意的问题
+ 意犹未尽的话
网友评论