09 | 怎么才能写好项目文档
我以前看过一个投票，盘点程序员不喜欢的事，有两条和文档相关：
- 不喜欢写文档；
- 不喜欢项目文档太少。
看起来很矛盾，却很现实。基本上大家都认同：“项目文档很重要”，然而我们在项目中总是短期高估文档的重要性，而长期低估文档的重要性。
那么为什么程序员都不爱写文档呢？我总结了一下大致有下面这些原因。
- 不知道怎么写
- 太忙没时间写或者懒得写
- 觉得敏捷开发不用写
为什么要写文档？
写文档，其实对个人、对项目、对团队，都是非常重要的事情。
- 帮助写文档的人理清楚思路
写文档，可以让你在写代码之前，梳理清楚思路，想清楚整体结构，比如说有哪些工作是重点难点；哪些要依赖其他人，需要及早协商的；哪些是要考虑安全性的。
先写文档，就会抛开代码细节，去站在全局思考。写的时候，各个模块之间的依赖关系、各种可能的安全隐患、各种可能需要其他人配合的地方，就都冒出来了，必须要去查资料，去找人讨论，反复缜密的思考后最终写出来。
真正的障碍是没想清楚，在心中只有一些未成型的混乱的想法和概念，必须要努力把这些模糊的想法确定化和具体化，才能写出来。
- 便于未来的维护和交接
“好记性不如烂笔头”，存在脑子里的内容是不可靠的，一个正常的项目组，如果需要长期维护，就需要一定的文档，把设计、操作流程、环境配置等内容记录下来，而不仅仅依赖于口口相传。
- 便于团队更好的协作沟通
如何写好文档
1.从模仿开始
模仿就是最好的写文档方式，尤其是现在网上可以参考的例子也很多，当你写文档不知道该如何下手的时候，不妨去找一个类似的文档，模仿着写试试
2. 从小文档开始
3. 从粗到细，迭代更新
我写一个大一点的文档，都是从脑图开始的，先基于脑图，把基本结构梳理清楚。然后第二步就是写 PPT，PPT 有个好处就是不用太多文字，列个一二三，画几张图，就是个简单的文档，PPT 还有个好处就是可以用来给别人讲解，收集反馈。写完 PPT，也收集好了反馈，再写正式的文档。先按照脑图列的提纲把主要章节放上去，然后把 PPT 上的内容和画的图放到文档中，一篇文档的骨架就搭好了，剩下的就是对细节的补充了。
4. 善于画图
- 线框图
线框图是最常用也最实用的一种图形，用简单的方框代替功能、模块、服务等，再用箭头表示关系或者数据流向，非常简单直接。
- 流程图
流程图是软件项目文档中一种常用图形，可以方便的表示各种不同条件下的逻辑路径。要画好流程图不难，重点是要理清楚逻辑关系，各个关键节点在不同条件下的走向。
例：重置密码流程图。
- 时序图
时序图也是软件项目所特有的一种图形，可以表示不同对象之间发送消息的时间顺序，尤其在涉及网络通信的文档中特别常用。画好时序图，关键是要列清楚所有涉及的对象或者服务，以及消息发送的先后顺序。
例：注销登录过程的时序图。
- 各种格式截图