一个现象
基本上大家都认同“项目文档很重要”，然而我们在项目中总是短期高估文档的重要性，而长期低估文档的重要性
结果就是口号喊的很响：要重视文档、要写好文档、要多写文档，然而随着项目的推进，总有比文档优先级更重要的任务，文档的优先级总是被有意无意推迟，导致项目的文档缺失、老旧、无人维护。
为什么程序员都不爱写文档呢
（1）不知道怎么写：不知道怎么写文档的应该占很大一部分比例。
（2）太忙没时间写或者懒得写
（3）敏捷开发所以不用写文档？这是不对的，敏捷宣言最后一句话明确指出：“尽管右项有其价值，我们更重视左项的价值。”也就是说敏捷从来没有否认文档的价值，只是更重视“工作的软件”罢了。
为什么要写文档
“大脑是用来计算的，并不是用来记忆的。” 学的东西越多，记住的内容往往越少，将重复或可整理的内容写成文字，保存起来，使用的时候知道去哪里找就好。这也正是索引 / 缓存的妙处，利用大脑有限的 Cache 资源缓存常用的内容索引，将不常用的内容存盘，需要的时候再次加载。
写文档，其实对个人、对项目、对团队，都是非常重要的事情。
（1）帮助写文档的人理清思路
- 写文档，可以让你在写代码之前，梳理清楚思路，想清楚整体结构，比如说有哪些工作是重点难点；哪些要依赖其他人，需要及早协商的；哪些是要考虑安全性的。
- 如果上手就写代码，就很容易陷入到某个技术细节中，而忽略了整体结构。写的时候才发现一个技术难点无法解决，或者已经在某个不重要的细节上浪费了很多时间；或是发现有些依赖其他人提供的服务还没准备好；又或者是上线后才发现有安全漏洞。
- 先写文档，就会抛开代码细节，去站在全局思考。写的时候，各个模块之间的依赖关系、各种可能的安全隐患、各种可能需要其他人配合的地方，就都冒出来了，必须要去查资料，去找人讨论，反复缜密的思考后最终写出来。
- 有人觉得自己写作不行，所以不会写文档。写作不行，只是让你在用词遣句上会有所欠缺，而这不是写文档的真正障碍。真正的障碍是没想清楚，在心中只有一些未成型的混乱的想法和概念，必须要努力把这些模糊的想法确定化和具体化，才能写出来。
- 换个角度来说，如果你连文档都写不出来，那又怎么能指望代码写得好呢？
（2）便于未来的维护内交接
- “好记性不如烂笔头”，存在脑子里的内容是不可靠的
- 一个正常的项目组，如果需要长期维护，就需要一定的文档，把设计、操作流程、环境配置等内容记录下来，而不仅仅依赖于口口相传。
（3）团队更好的协作沟通
- 在一个项目组中，大家都有不同的分工，有人负责产品设计，有人负责架构设计，有人负责测试。而文档，就成为了团队成员很好的沟通工具
- 比如说产品设计有雏形的时候，会有一个产品设计的评审会议，基于文档，项目成员可以一起参与其中，提出自己的意见和看法。这样就不至于等到产品设计出来之后，大家才对于设计有改进想法或者意见，造成无法更改的结果
如何写好文档
从模仿开始
模仿就是最好的写文档方式，尤其是现在网上可以参考的例子也很多，当你写文档不知道该如何下手的时候，不妨去找一个类似的文档，模仿着写试试。
从小文档开始
一开始写文档，内容不需要很多，可以从小的文档开始。可以记一些笔记，不要在意格式，一两句话，一些截图，就是不错的笔记。
项目中很多文档都可以从这样小的内容开始：别人给你讲一个问题的时候记录下来；你给别人讲一个问题的时候记录下来；解决一个技术难题时记录下来方案……
这些记录下来的笔记，稍加整理，就可以是很不错的项目文档。
从粗到细，迭代更新
- 第一步是列提纲，从从脑图开始的，先基于脑图，把基本结构梳理清楚。
- 然后第二步就是写 PPT，PPT 有个好处就是不用太多文字，列个一二三，画几张图，就是个简单的文档，PPT 还有个好处就是可以用来给别人讲解，收集反馈。
- 写完 PPT，也收集好了反馈，再写正式的文档。先按照脑图列的提纲把主要章节放上去，然后把 PPT 上的内容和画的图放到文档中，一篇文档的骨架就搭好了，剩下的就是对细节的补充了。
为什么我不一开始就写很细的文档呢？
- 一个原因是太难写，要花很多时间精力，甚至可能写不下去；
- 另一个原因就是在收集反馈的过程中，会有很多修改。写得越细则无用功越多，最后，你甚至会因为不想改文档而抵触不同的意见。
而从粗到细逐步迭代的方式就好多了，一开始的目的是为了梳理清楚思路，只要脑图这种级别的内容就好了，然后进行调整。因为文档很粗，调整也方便，等到基本确定后再写细节，就不会有大的反复。
一些基本的画图的技巧
“字不如表，表不如图，一图胜千言”。好的图能帮助你简
单而直观地把问题说明清楚。
画图其实不复杂，不需要多专业的绘画技巧，也有很多工具软件可以帮助我们简化操作，像Visio、PowerPoint、Keynote、OmniGraffle 等都是很好的画图软件。平时看到好的图也要注意收集整理，以后自己写的时候，也可以直接参考，可以帮你少走弯路。
写文档的时候，主要有几种图比较常用：线框图、流程图、时序图、各种格式的截图。
线框图
线框图是最常用也最实用的一种图形，用简单的方框代替功能、模块、服务等，再用箭头表示关系或者数据流向，非常简单直接。
要画好线框图并不难，主要是要理清楚有哪些模块，以及模块之间的关系是什么。用方框配上文字表示模块，方框之间的连线和箭头表示关系。
看几个例子：
流程图
流程图是软件项目文档中一种常用图形，可以方便的表示各种不同条件下的逻辑路径。
要画好流程图不难，重点是要理清楚逻辑关系，各个关键节点在不同条件下的走向。
时序图
时序图也是软件项目所特有的一种图形，可以表示不同对象之间发送消息的时间顺序，尤其是在涉及网络通信的文档中特别常用。
画好时序图，关键是要列清楚所有涉及的对象或者服务，以及消息发送的先后顺序。
各种格式截图
截图也是个非常简单直接的方式，把软件的 UI、交互设计的效果、数据趋势图、数据统计图等直接截图，必要的话配上一些箭头、文字，也可以很好的说明清楚问题。尤其是产品设计文档，经常用到。
其他建议
文档很重要，但是工作的软件高于详尽的文档。这里面的平衡很重要。
不需要为代码写很多文档，好的代码格式，良好的注释、完善的单元测试可以很大程度上代替针对代码而写的文档。
Markdown 是一种非常好的文档格式，可以让你更专注于内容上，而不是文档格式上面。
在线文档工具优于离线文档工具，在线文档有很好的版本管理，也更方便多人协作。像Github WIKI、石墨文档、Google Docs、Evernote 等都是非常好的在线文档工具。
对于文档的撰写，要作为一个正规的项目任务进行，安排人、安排时间，放到项目计划中去。就像前面说的“懒得写”文档的情况，一旦把文档当成一个与开发同等重要的任务去执行，就没有借口去犯懒了。
重要的是，文档的写作一样需要多练习，写的越多，就越熟练。
一般需要写哪些文档
（1）项目立项
- 原始需求文档
- 可行性分析报告
- 立项说明书
（2）需求相关的
- 原型设计文档
- 产品设计文档
（3）系统设计相关的
- 技术方案文档
- 详细设计文档
（4）开发相关的
- 代码规范文档
（5）测试相关的
- 测试用例
- 测试验收报告
（6）运维相关的：
- 部署文档
- 故障报告
其实没有特别的标准的，还是根据各个阶段需要。原则上就是：
- 这件事需要讨论需要评审，要有文档作为讨论的依据，以及记录讨论的结果。比如各种设计文
档 - 这件事要有规范，要有文档保证规范统一。比如各种规范文档
- 这件事要记录下来，作为以后的一个参考。比如各种报告、环境配置、操作手册、API文档等
问题： 对于详细设计文档的颗粒度一直有点疑问。
是写到类图或者时序图这种级别，说明不同类和方法之间的关系？
还是要细化到类似于伪代码级别，需要写操作哪个数据库表，和调用哪个api接口。
很多年前，推荐的写设计文档就是你说的这种细化到为伪代码级别，当时初衷是学习建筑行业，把写代码变成像搬砖砌墙一样，招一堆蓝翔培训出来就可以写代码。据说当年日本软件产业就是这样的。
实际上这些年下来，这种方法是不可行的（至少我没看到过成功案例），一个是设计文档写得太细，其实成本上已经跟写代码没差别了，不利于分工协作；另一个是写代码本身是一种创造性的劳动，当你把文档写到伪代码那么细，具体负责代码实现的没什么好发挥的空间了，都变成体力劳动了。
推荐的做法是写设计文档时不要太细，同时应该把具体模块的设计交给负责这个模块开发的人去做，指导他完成设计。这样既可以更好的分工协作，也可以让程序员有机会成长和充分发挥其主观能动性。