项目文档的分类

项目文档的分类

项目文档的重要性

项目文档的重要性

常见的误区

1. 写文档是浪费时间？没时间写文档？
   • 文档本身也是产出：coding的时间少于30%
   • 写文档是整理思路的过程：打字速度应快于思考速度
   • 没有文档，后期会花费更多的维护成本
2. 这是个简单的项目/问题，不需要文档？
   • 项目的延续时间和复杂性往往超出预期
   • 早期的“偷懒”，往往在后期会付出代价

常见的问题

• 没有接口文档：多人协作出现问题
• 需求文档没写好：
  • 多次反复讨论同样的问题
• 没有系统总体架构文档：
  • 每个人都需要重新看代码，还不一定能看清
• 缺少文档
  • 新人无从入手
  • 人员变动时，不好交接
  • 团队内沟通效率很低
  • 自己过两个月后，痛苦的回忆之前的思路

什么时候需要写文档？

• 必须的文档
  • 需求设计文档：需求，重点，取舍过程
  • 接口文档：函数，参数，返回值
  • 关键性的算法文档：思路，关键点
  • 系统总体框架：全局的思路
• 凡是不那么“显而易见”的地方，最好都留下文档
• 不仅留下设计结果（what）,也留下思考 过程（why）
  • 留下决策的依据，便于后面的工作
• 文档不是写完代码后补出来的
  • 文档是设计过程中使用的工具、和设计过程的结果

文档的书写方法

• 拉提纲，自顶向下
  • 大的标题下，列出子问题
  • 再对每个子问题逐步展开
• 反刍
  • 感觉不好之后要及时修改
    一句，一段，甚至整个文章的结构
  • 逐步提高自己写文档的能力
• 让重要的内容醒目
  • 标题；段首第一句话
  • 加重、有颜色、或者带下划线的文字