在工作中，文档对我们的重要性不言而喻。简单的来说，我们写文档的目的有3点：
第一，是为了给自己看，工作过一段时间之后我们自己也会忘记关于当初所编写的代码、所做的实施操作是什么，那么为了能够让自己的大脑快速恢复场景，有必要将当前发生过的事情用文档的形式记录一个“快照”，因此我们正确理解文档的作用，首先就是一个快照。
第二，是为了给别人看，无论是项目要码人还是准备要在未来晋升，文档都是可以用来节约你时间的最好工具，举个例子来说，如果你把刚刚加入项目组的新人拉到一边不厌其烦的去讲这个项目的前世今生，不仅你会烦，听的人也会犯困。口述的知识传递量毕竟有限，如果对方不做笔记，或者讲述者忘记了一些细节，到时候沟通成本将会成指数级增加。那么一篇好的文档发送给别人，就可以降低你的沟通成本。
第三，是为了技术或者技能提炼或升级。写文档写的多了，便自然会发现相似文档中的套路，比如实施过程中需要建立表空间，每一次写文档的时候如果都加上了，写文档的人也会觉得烦，于是便专项提炼出“如何按标准建立表空间和用户”的文档，以后再有类似操作，后续的文档完全可以写：“请参见《如何按标准建立表空间和用户》”，这就是技能提炼。如果突然有一天发现知识库中有几百篇实施操作或者技术文档是讲类似的操作，则可以将这种操作升华为方法论（没有大量实践经验直接拍脑袋想出来的方法论往往都会以失败而告终），规避各种疑难杂症，甚至从中发现普适性的问题（比如每一个项目都要配置各个服务IP地址，非常麻烦），从而迸发出创造力，将普适性问题解决（比如需要都配置服务IP地址，还要注意客户网络环境不能变，因此为了解决它，想到了用服务发现来解决IP地址漂移的问题），从而实现技术升级。
1、先用5分钟列出个12345
我们使用的工具可以是Word，也可以是Markdown编辑器，无论是什么样的工具，我们都可以通过设想个12345来解决：第一是什么，第二是什么，第三是什么……。这种思维属于结构化思维，如果暂时想不到，我们可以不妨用这种思维模式来扩展一下：我们想要做什么？怎么去做？最终结果应该如何？
这就和人生三大哲学问题是一样的：我从哪里来？我是做什么的？我又要到哪里去？
比如我们要写一篇需求文档，一般套路是：1、需求描述；2、流程设计（或原型设计）；3、实施目标
再比如我们要写一篇系统详细设计文档，一般套路是：1、系统设计目标；2、架构设计；3、原型设计；4、流程规则；5、安装部署
总的来说，文章应当符合总分总结构，即总览、分述、总结。
在Word里有标题的设置，我们可以先列标题1（即1级标题），然后再根据每个标题列出来标题2（即2级标题） ，通过标题的设置，很快就可以建立起一篇文档的脉络。
我们所接触的80%的文档其实是不用列二级标题的，如果文档的页数超过10页，则建议将二级标题列出来，同样也是采用列12345的方式。比如说流程设计我们按系统角色的维度扩展开，可以写成：1、系统管理员操作流程；2、租户操作流程；3、访客操作流程；4、审计人员操作流程
切忌一篇简单的文档把它细分复杂了，为了方便阅读，一定要把文档写简答了。讲一个如何处理ORA-00119的报错问题，标题就是以报错编码为标题，比如“解决Oracle数据库ORA-00119报错”，把解决的领域和具体报错信息作为标题方便查找。然后大纲写：1、问题产生的过程；2、处理方式；3、验证
一个简单的三段论就可以把ORA-00119讲透彻
2、用20分钟把每件事情讲的恰到好处
列完大纲之后，我们就要对文档的内容进行填充了。这里面我们要把握好文档的字数和文档的度量。毕竟文档首先是要给自己看的，写的太复杂也并不会有人给午饭加鸡腿，打字还蛮累的对不。所以如果一篇文档是写给程序员的，我们就假定这个程序员一定具备了基本的环境部署能力、代码阅读能力，因此就没有必要将大篇幅的代码粘贴到文档中让其他程序员来看，只需要提取最为关键的部分即可。比如讲JDBC如何动态获取字段的文章，我们就简单的说：在获取到ResultSet对象之后，调用getMetaData方法可以获取字段元数据信息，里面就包含了字段名，用法详见代码com.yangruoyu.Demo，这个时候如果再讲JDBC是什么、DriverManager又是什么、怎么建立PreparedStatement，或者干脆把200行代码全粘上（如果是50行以内直接能跑，粘上倒也无妨，反而更直观），显然是不合时宜的。
再比如文档要讲一个需求，给客户看的话不要提数据库、字段、时间复杂度，直接说要做什么、我们会把界面做成什么样子即可。因为这篇文档我们的目的是为了让客户短时间看明白，同时做出反馈，及时告知我们是不是他们最初想象的那样子。
同样还是需求文档，给程序员看的话，就不要提“随着科学技术的进步和互联网的普及”这种套话，直接就说我们要改哪个界面（截一张图会更好）、涉及哪些字段、字段和字段之间什么关系、它们是怎么计算的（涉及流程的建议画个流程图）。因为这篇文档的目的是为了让程序员更快的理解需求，把代码写出来。意义固然很重要，但是在项目时间安排上，做这个需求是否有意义得等复盘再说，当下先要满足客户需求。
同样的，程序员如果写给项目负责人的部署说明文档，就不要提用了什么技术、数据库字段是什么。直截了当的就是把程序放在哪个目录下、是否得重启系统、如果进到系统界面里看到了某个东西（给张截图会更加清晰）就算是这个程序成功运行了。
总之，就是文章中只写最简单的、对方最关心的那个点。其余的内容完全不必写。
因此大多数文档可能一张A4纸就能承载。这种文档无疑是成功的。
为了能够描述清楚，文章中的图片覆盖率建议在25%左右，可以画流程图、原型图、UML图、脑图，甚至是屏幕截图。总之，一张图胜过千言万语，为了让其他人能懂，这都是值得的。
脑图的样例
3、用5分钟时间整理
把文档按时间编码（比如文件名以20200331_0630开头，方便按文件名排序，文档先后顺序一看便知）、传到知识库（或网盘），然后发给需要的人看即可。写文档是个功夫，需要不断练习。连续写上4、5篇，写文档的感觉就有了。
如果以后有人再问XX产品的架构是怎么回事、XX的配置怎么做，一篇文档发过去，轻松又便捷。