引子
- 太多程序员(包括很多资深程序员)不会写文档
- 太多项目没有(完整)文档
- 即使有文档，这些文档达标了吗
- 你对文档有正确的认识吗
- 你会写文档吗
- 软件项目的文档，可有可无吗
目录
- 项目文档的重要性
- 文档书写规范
- 文档的存放
- 文档内容的书写
- 文档的配图
- 文档的review
- 怎么提高写文档的能力
项目文档的重要性
文档的目的
- 提高沟通的效率
- 提升对”思考过程“的管理
项目中，超过50%的时间用于沟通,提高沟通的效率非常重要
沟通的方式: 口头，文档，代码
对思考过程的管理
- 项目中常常面临数不清的问题(“线头”)
- 理清问题，挑出重点，深入挖掘
常见的误区
1.写文档是浪费时间？没时间写文档？
- 文档本身也是产出: coding的时间少于30%
- 写文档是整理思路的过程: 打字的速度应该快于思考的速度
- 没有文档,后期会花费更多的维护成本
2.没写需求和设计文档就开始写程序？
- 修改文档，比修改代码的成本小的多
3.这是个简单的项目/问题，不需要文档？
- 项目的延续时间和复杂性往往超出预期
- 早期的”偷懒“，往往在后期会付出代价
常见的问题
- 没有接口文档
多人协作出现问题 - 需求文档没写好:
多次反复讨论同样的问题 - 没有系统总体架构文档
每个人都需要重新看代码，还不一定能看清 - 缺少文档
- 新人无从下手
- 人员变动时，不好交接
- 团队内沟通效率很低
- 自己过两个月后，痛苦的回忆之间的思路
什么时候需要写文档
必须的文档
- 需求设计文档: 需求，重点，取舍过程
- 接口文档: 函数，参数，返回值
- 关键性的算法文档: 思路，关键点
- 系统总体框架: 全局的思路
凡是不那么”显而易见“的地方，最好都留下文档
文档中不仅仅要留下设计的结果，也要留下思考的过程: 留下决策的依据，便于后面的工作
文档不是写完代码后补出来的
文档是设计过程中使用的工具和设计过程的结果
选用合适的表述模式
不同种类的问题，有不同的模式
- 分析和解决一个问题: 提出问题，分析问题，解决问题
- 提出一个实现的建议: 出发点，手段，工作量估计，收益的估计
- 系统的设计: 模块，功能，过程
- 程序的设计: 数据，函数，模块，调用过程，系统结构
好的文档实践
索引
索引对提升文档使用效率非常关键
可基于wiki建立文档索引
示例:
http://wiki.baidu.com/pages/viewpage.action?pageId=326172401
http://wiki.baidu.com/pages/viewpage.action?pageId=108771491
怎么提高写文档的能力
- 一个普遍的误区,”我对这个项目非常清楚，我只是不会写文档“
你错了！写不好文档的原因是没有想清楚 - 提高写文档的能力的本质
最根本还是提高分析问题的能力，提高设计系统的能力 - 多看好的文档
好的教科书(不仅仅告诉你what，而且分析why，要注意看分析过程)
好的论文(很多发表的(尤其是写系统的)论文，可能原来就是一个设计文档) - 多写
多改(自己给自己挑毛病，类似禁用笔下周伯通的左右互博)
多互相review(看一遍别人的文档，也是很好的训练)