已剪辑自: https://blog.csdn.net/houzhizhen/article/details/105622282
引子
- 有太多的程序员（包括很多资深的程序员）不会写文档
- 有太多的项目没有（完整的）文档
- 即使有文档，这些文档达标了吗？
- 你对文档有正确的认识吗？
- 你会写文档吗？？
- 软件项目的文档是可有可无的吗？
目录
- 项目文档的重要性
- 文档的目的：
- 项目中，超过50%的时间用于沟通
- 沟通的方式
- 对“思考过程”的管理
- 项目中常常面临数不清的问题（“线头”）
- 理清问题，挑出重点， 深入挖掘
常见的误区
常见的问题
-
没有接口文档：多人协作出现问题
-
需求文档没写好：
-
没有系统总体架构文档：
-
每个人都需要重新看代码，还不一定能看请
-
缺少文档：
-
新人无从入手
-
人员变动时、不好交接
-
团队内部沟通效率很低
-
自己过两个月后，痛苦的回忆之前的思路
什么时候需要些文档？
- 必须的文档
- 需求设计文档：需求， 重点，取舍过程
- 接口文档： 函数， 参数， 返回值
- 边界性的算法文档： 思路， 关键点
- 系统总体框架： 全局的思路
- 凡是不那么“显而易见”的地方，最好都留下文档
- 文档中不仅仅留下设计的结果（what), 也要留下思考的过程（why）: 留下决策的依据，便于后面的工作
- 文档不是写完代码后补出来的！
文档书写规范
-
封面
-
历史说明
-
修订人、修改日期、修改说明
-
字体
-
宋体，五号字， 单倍行距
-
文档结构
-
分层次的标题
文档的存放
-
这里推荐一个比较实用的做法
-
你可以根据自己的情况来设计一个存档方式
-
将文档（word格式)保存在svn上
-
容易看到本地和远程的不一致
-
在wiki上建立文档的索引
-
便于看请全局的情况（内容分布，时间分布）
文档内容的书写
文档的格式
-
格式表现的是一种逻辑
-
可能的逻辑关系： 总-分，递进， 并列， …
-
标题
- 标题是否表达文档的内容
- 标题是否和文档的内容相符合
- 各层标题所构成的提纲，是否能清晰反映文档的内容？
-
段落
- 段首一定要有缩进
- 段落不要太长
- 注意每段的第一句话
- 每段内的多句话应该有一定的逻辑
文档中问题的划分
选用合适的表述模式
- 不同种类的问题，有不同的模式
- 分析和解决一个问题： 提出问题，分析问题，解决问题
- 提出一个实现的建议： 出发点（目的），手段，工作量估计，收益的估计
- 系统的设计： 模块，功能，过程
- 程序的设计： 数据，函数，模块，调用过程，系统结构
文档的评价
文档的书写方法
文档中配图的指南
文档的review
怎么提高写文档的能力
-
一个普遍的误区
-
我对这个项目都非常清楚，我只是不会写文档
-
你错了！写不好文档的根本原因是没有想清楚！
-
提高写文档的能力的本质
-
最根本还是提高分析问题的能力， 提高设计系统的能力
-
多看好的文档
-
好的教科书（不仅仅告诉你what, 而且分析why,要注意看分析过程）
-
好的论文（很多发表的（尤其写系统的）论文，可能原来就是一个设计文档）
-
多些（自己给自己挑毛病。类似金庸笔下周伯通的左右互搏）
-
多相互review(看一遍别人的文档，也是很好的训练)
本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)
