如何写好项目文档

已剪辑自: https://blog.youkuaiyun.com/houzhizhen/article/details/105622282

引子

• 有太多的程序员（包括很多资深的程序员）不会写文档
• 有太多的项目没有（完整的）文档
• 即使有文档，这些文档达标了吗？
• 你对文档有正确的认识吗？
• 你会写文档吗？？
• 软件项目的文档是可有可无的吗？

目录

• 项目文档的重要性
• 文档的目的：
  • 提高沟通的效率
  • 提升对“思考过程”的管理
• 项目中，超过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(看一遍别人的文档，也是很好的训练)