引子
-
有太多的程序员（包括很多资深的程序员）不会写文档
-
有太多的项目没有（完整的）文档
-
即使有文档，这些文档达标了吗？
-
你对文档有正确的认识吗？
-
你会写文档吗？？
-
软件项目的文档是可有可无的吗？
目录
- 项目文档的重要性
- 文档的目的：
- 提高沟通的效率
- 提升对“思考过程”的管理
- 项目中，超过50%的时间用于沟通
- 提高沟通的效率非常重要
- 沟通的方式
- 口头， 文档， 代码
- 对“思考过程”的管理
- 项目中常常面临数不清的问题（“线头”）
- 理清问题，挑出重点， 深入挖掘
常见的误区
- 写文档是浪费时间？ 没时间写文档？
- 文档本身也是产出： coding 的时间少于30%。
- 写文档是整理思路的过程：打字的速度应该快要思考的速度
- 没有文档，后期会花费更多的维护成本
- 没有需求和设计文档就开始写程序？
- 修改文档，比修改代码的成本小的多。（）
- 这是个简单的项目/问题，不需要文档？
- 项目的延续时间和复杂性往往超出预期
- 早期的“偷懒”， 往往在后期会付出代价
常见的问题
- 没有接口文档：多人协作出现问题
- 需求文档没写好：
- 多次反复讨论同样的问题
- 没有系统总体架构文档：
- 每个人都需要重新看代码，还不一定能看请
- 缺少文档：
- 新人无从入手
- 人员变动时、不好交接
- 团队内部沟通效率很低
- 自己过两个月后，痛苦的回忆之前的思路
什么时候需要些文档？
-
必须的文档
- 需求设计文档：需求， 重点，取舍过程
- 接口文档： 函数， 参数， 返回值
- 边界性的算法文档： 思路， 关键点
- 系统总体框架： 全局的思路
-
凡是不那么“显而易见”的地方，最好都留下文档
-
文档中不仅仅留下设计的结果（what), 也要留下思考的过程（why）: 留下决策的依据，便于后面的工作
-
文档不是写完代码后补出来的！
- 文档是设计过程中使用的工具、和设计过程的结果
文档书写规范
- 封面
- 编号（用于Reference），项目，版本号
- 历史说明
- 修订人、修改日期、修改说明
- 字体
- 宋体，五号字， 单倍行距
- 文档结构
- 分层次的标题
文档的存放
- 这里推荐一个比较实用的做法
- 你可以根据自己的情况来设计一个存档方式
- 将文档（word格式)保存在svn上
- 容易看到本地和远程的不一致
- 在wiki上建立文档的索引
- 便于看请全局的情况（内容分布，时间分布）
文档内容的书写
- 文档的格式
- 文档的逻辑
- 文档的评价
- 文档的书写方法
文档的格式
- 格式表现的是一种逻辑
- 可能的逻辑关系： 总-分，递进， 并列， …
- 标题
- 标题是否表达文档的内容
- 标题是否和文档的内容相符合
- 各层标题所构成的提纲，是否能清晰反映文档的内容？
- 段落
- 段首一定要有缩进
- 段落不要太长
- 注意每段的第一句话
- 每段内的多句话应该有一定的逻辑
文档中问题的划分
- 选择合适的角度
- 从不同的角度看到的东西是不一样的（类比：汽车不同角度的riew）
- 角度的说明： 说明划分问题的出发角度
- 注意联系： 子问题之间的联系
- 是否是一个独立的问题
- 切分问题是否准确
- 是否是一个重要的问题
- 决定写作的详略。
选用合适的表述模式
- 不同种类的问题，有不同的模式
- 分析和解决一个问题： 提出问题，分析问题，解决问题
- 提出一个实现的建议： 出发点（目的），手段，工作量估计，收益的估计
- 系统的设计： 模块，功能，过程
- 程序的设计： 数据，函数，模块，调用过程，系统结构
文档的评价
- 文档是写给别人看的！
- 能否让读者在5分钟内看懂
- 能否做到问题清楚、重点突出、逻辑清楚？
- 能否做到言之有物： 不要死套格式
- 能否做到言简意赅：不要说废话
- 能否避免造成别人的误解
- 不要说模棱两可的话
- 要注意自己的表达是否通俗（有太多人说“自己才懂的方言”）
文档的书写方法
- 拉提纲，自顶向下
- 大的标题下列出子问题，再对每个子问题逐步展开
- 反刍
- 感觉（一句，一段，甚至整个文章的结构）不好之后要及时修改
- 提高自己写文档的能力
- 让重要的内容醒目
- 标题： 段首第一句话：
- 加重、有颜色、或者带下划线的文字
文档中配图的指南
- 要明确这个图片的目的
- 只能展现1-2个（最好是一个）主要问题
- 只能说明一个层次上的问题
- 要明确图片中传递信息的重点
- 要注意图片中面积的使用
- 可能错误：太多空白的区域，说明的文字过小
- 图片最好能独立说明一个事情
- 同时太多的关注点 =》 失焦
- 对于图片中不能明确表达的地方，需要在图片周围的文字部分给出辅助的说明
文档的review
- 有太多文档的review是无效的！
-Q（leader): 这个文档你reciew过了， 为什么质量还这么差？！
-A（reviewer)：这个文档的内容我也感觉是模模糊糊的… - 甚至有很多文档写出后，根本就没有被（仔细）看过
- 写这样的文档有什么用？
- 文档的review是一次在大脑中的“重放过程”
- 尝试follow作者的思路，看看是否可以走通
- 是否有遗漏的内容
- 文档review的产出
- 在文档中插入comment
- 直接对文档进行修订
- Word提供了很好的功能，你也可以选用其它工具
怎么提高写文档的能力
- 一个普遍的误区
- 我对这个项目都非常清楚，我只是不会写文档
- 你错了！写不好文档的根本原因是没有想清楚！
- 提高写文档的能力的本质
- 最根本还是提高分析问题的能力， 提高设计系统的能力
- 多看好的文档
- 好的教科书（不仅仅告诉你what, 而且分析why,要注意看分析过程）
- 好的论文（很多发表的（尤其写系统的）论文，可能原来就是一个设计文档）
- 多些（自己给自己挑毛病。类似金庸笔下周伯通的左右互搏）
- 多相互review(看一遍别人的文档，也是很好的训练)