引子
有太多的程序员（包括很多资深的程序员）不会写文档
有太多的项目没有（完整的）文档
即使有文档，这些文档达标了吗？
你对文档有正确的认识吗？
你会写文档吗？？
软件项目的文档是可有可无的吗？
目录
项目文档的重要性文档的目的：
提高沟通的效率提升对“思考过程”的管理
项目中，超过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(看一遍别人的文档，也是很好的训练)