项目文档的分类
项目文档的分类
项目文档的重要性
项目文档的重要性
常见的误区
- 写文档是浪费时间？没时间写文档？
- 文档本身也是产出：coding的时间少于30%
- 写文档是整理思路的过程：打字速度应快于思考速度
- 没有文档，后期会花费更多的维护成本
- 这是个简单的项目/问题，不需要文档？
- 项目的延续时间和复杂性往往超出预期
- 早期的“偷懒”，往往在后期会付出代价
常见的问题
- 没有接口文档：多人协作出现问题
- 需求文档没写好：
- 多次反复讨论同样的问题
- 没有系统总体架构文档：
- 每个人都需要重新看代码，还不一定能看清
- 缺少文档
- 新人无从入手
- 人员变动时，不好交接
- 团队内沟通效率很低
- 自己过两个月后，痛苦的回忆之前的思路
什么时候需要写文档？
- 必须的文档
- 需求设计文档：需求，重点，取舍过程
- 接口文档：函数，参数，返回值
- 关键性的算法文档：思路，关键点
- 系统总体框架：全局的思路
- 凡是不那么“显而易见”的地方，最好都留下文档
- 不仅留下设计结果（what）,也留下思考 过程（why）
- 留下决策的依据，便于后面的工作
- 文档不是写完代码后补出来的
- 文档是设计过程中使用的工具、和设计过程的结果
文档的书写方法
- 拉提纲，自顶向下
- 大的标题下，列出子问题
- 再对每个子问题逐步展开
-
反刍
- 感觉不好之后要及时修改
一句，一段，甚至整个文章的结构 - 逐步提高自己写文档的能力
- 感觉不好之后要及时修改
- 让重要的内容醒目
- 标题；段首第一句话
- 加重、有颜色、或者带下划线的文字
