我们一直针对项目文档有一种矛盾的疑惑，自己不喜欢写文档和不喜欢别人没有写文档。我们都知道项目文档很重要，但是我们总是在项目中短期高估文档的重要性，长期低估文档的重要性；结果口号喊得很响，要重视文档，要写好文档，要多些文档，但是在项目推进中，总有比文档优先级更重要的任务，文档总是被退后，导致项目文档缺失、老旧、无人维护。
我总结了下程序员为啥不爱写文档，首先不知道怎么写，其次太忙没时间写或者懒得写，程序员忙的时候情有可原，不忙的时候也很少去写文档，宁可去想代码怎么重构，其实还是太懒；敏捷开发不用写文档？这个是大家都存在的误区，敏捷开发从来没有否认文档的价值，只是更重视“工作的软件”。
为什么要写文档？写文档，对个人、项目和团队非常重要，首先帮助写文档的人理清楚思路，因为写作的过程，就是一个思考的过程，写文档，可以让我们在写代码之前，梳理清楚思路，想清楚整体架构，如果一开始就开始写代码，会陷入技术细节中，忽略了整体结构；其次先写文档，会抛开代码细节，站在全局思考，每个模块之间的依赖关系、存在安全隐患，这些都需要去讨论咨询、查询资料、反复缜密思考才最终写出来，其实真正的写文档障碍是没有想清楚，心中只有一些未成型的混乱的想法和概念，我们必须努力把模糊的想法确定化和具体化，换个角度，如果我们连文档都写不出来，还能指望代码写的好么？
写文档有哪些好处呢？
1.便与未来的维护和交接
“好记性不如烂笔头”，存在脑子里的内容是不可靠的，一个正常的项目组，如果要长期维护，就需要有一定的文档，记录设计、操作流程、配置环境等。
2.团队更好的协作沟通
团队成员间通过文档更好的沟通，例如产品设计雏形期会有产品设计的评审会议，基于文档，项目成员一起参与其中讨论。
如何写好文档？
1.从模仿开始
“依葫芦画瓢”，学习别人的文档格式，
2.从小文档开始
3.从粗到细，迭代更新
我们小时候写作文都是要求提纲挈领，先列提纲，把基本结构梳理清楚，然后写PPT，PPT好处是不用太多文字，列个一二三，画几张图，就是简单文档，主要PPT是拿来收集反馈，然后一篇文档的骨架就搭好了，剩下细节补充。
为什么不一开始就写很细的文档，因为太难写，要花很多时间精力，而且收集反馈的过程中会有很多修改，写的越细无用功越多，最后甚至会因为不想改文档而抵触不同的意见。
从粗到细迭代一开始是为了梳理清楚大概思路，然后确定基本细节。
1.基本的画图技巧
"字不如表，表不如图，一图胜千言"；用好画图软件Visio、PowerPoint、Keynote、OmniGraffle等，比较常用的图有线框图、流程图和时序图
2.线框图
线框图用简单的方框代替功能、模块、服务，用箭头表示关系或者数据流向。看看Twitter当前的缓存方案：
例如Netflix的账单系统架构图
- 流程图
流程图表示各种不同条件下的逻辑路径，重点在于梳理清楚逻辑关系，各个关键节点不同条件下的走向。
例如重置密码流程图
- 时序图
时序图表示不同对象之间发送消息的时间顺序，涉及通络通信中特别常用，重点要清楚所有涉及的对象或者服务，以及消息发送的先后顺序。
例如注销登录过程的时序图
- 各种格式截图
软件UI、交互设计效果、数据趋势图、数据统计图直接截图配上箭头、文字。
还有，不需要过度追求文档的花哨，把大量时间浪费在写文档上，我们一直推崇敏捷宣言的观点，文档很重要，但工作的软件高于详尽的文档，平衡最重要。好的代码格式、良好的注释、完善的单元测试代码很大程度上代替针对代码而写的文档。
我极力推荐Markdown文档格式，让我们更专注于内容而不是根式，后续会专门弄一个Markdown的介绍文档。
最后总结就是，文档的写作要多练习，写的越多，就越熟练。