11、项目规划篇-项目文档

一、为什么要写文档？

1、帮助写文档的人理清思路

先写文档，就需要抛开代码细节，去站在全局思考，写作的过程，就是思考的过程。
写文档可以帮助在写代码之前理清思路和想清整体结构，必须努力把心中一些未成型的混乱的想法和概念确定化和具体化，才能写出来。

2、便于未来的维护和交接

一个正常的项目组，如果需要长期维护，就需要一定的文档，把设计、操作流程、环境配置等内容记录下来，而不能依赖于口口相传。
另外把日常工作中遇到的问题、各种环境配置、一些操作步骤，还有其他可能还会用的上的都记录下来。

3、便于团队更好的沟通协作

文档是团队成员很好的沟通工具。

二、如何写好文档

很多人不是不爱写文档，而是不知道如何写好文档。写好文档，关键是通过文档把想法表达出来，用词、格式都是次要的。

1、从模仿开始，模仿是最好的写文档方式

2、从小文档做起，之后再整理

3、从粗到细，迭代更新

一开始的目的是梳理清楚思路，只要脑图/PPT这种级别的就够了，在收集反馈的过程中会有很多修改，等到基本确定后再写细节，就不会有大的反复。

4、一些写文档时常用的图

俗话说：一图胜千言，写文档的时候，主要有几种图比较常用：线框图、流程图、时序图、截图。
线框图
用简单的方框代替功能、模块、服务等，再用剪头表示关系或者数据流，简单直接。需要理清有哪些模块，模块之间的关系。如下Netflix账单系统架构图。

流程图
要画好流程图，重点是理清楚逻辑关系，各个关键节点在不同条件下的走向。如下重置密码流程图。

时序图
可以表示不同对象之间发送消息的时间顺序，在涉及网络通信的文档中经常使用。
关键是列清楚所有涉及的对象或者服务，以及消息发送的先后顺序。

其他建议

最后，也不要陷入过于追求文档的情况中去，花大量的时间写一些形式化的没太大意义的文档。
文档很重要，但是工作的软件高于详尽的文档。这里面的平衡很重要。
不需要为代码写很多文档，好的代码格式，良好的注释、完善的单元测试可以很大程度上代替针对代码而写的文档。