如何写作一篇好文档
文档的作用在很多时候被严重低估。人们花在写文档上的时间也通常严重不足，因为它不能带来即时可见的效益；也因为好文档实在太少，让太多人觉得写文档这件事不值得花太多时间。你的领导或者客户也许更关注你是否正在为他们的需求忙碌，是否能为他们给你的任务不断地提交新的代码，而文档这件事似乎总是只与你自己有关，问就是优先级不高，还有其他更重要更紧急的任务。如果你真的把写文档这件事的优先级放低了，那恭喜，你一定会陷入一种现在很流行的窘境：本来应该从从容容，游刃有余；现在是匆匆忙忙，连滚带爬。
1. 文档的基本作用
“没错，在工作的过程中，写文档就是为了提高工作效率，而不是为了整理一套漂亮工整的报告去评选什么‘最美笔记大赛’。”
那么文档有什么用？简而言之，文档本质上是一种教学，把你知道的知识通过文字的方式表达出来，教给阅读文档的人（也包括将来的自己）。
文档第一个最重要的作用就是帮助你学习知识。我们通常把这种通过教别人巩固自己知识的方法称为费曼学习法(Feynman Technique)，由美国物理学家理查德·费曼(Richard Feynman)提出。费曼认为“如果你不能把某件事讲清楚给别人听，那你就还没有真正理解它”。相信大家都上过不少课，也看过不少视频和书籍。这些视频和书籍里有很多知识点，你被灌输了一次，但如果一段时间不用，不通过自己的方式把知识组织成一套系统，很快就会都还给老师，最后感觉什么也没有学会。这个世界上大部分人都是这么被动式学习的，学了忘，忘了学，只有很少的人会花时间和精力构建自己的知识体系，所以从心理上完全不用担心写文档占用了你的时间，因为你在构建一套体系，日后体系化作战的能力完全能对不写文档的人形成降维打击。此外，针对写文档，一定要牢记一个最重要的观念：不要吝啬把自己知道的知识分享出来，它会帮到别人，也会帮到你自己。这其实是一种开源思维，其他人对你文档的反馈也能进一步提升你的写文档水平和你自己对知识的理解程度。
文档的第二个作用是提高工作效率。没错，在工作的过程中，写文档就是为了提高工作效率，而不是为了整理一套漂亮工整的报告去评选什么“最美笔记大赛”。对于技术类的工作，我们平时会涉及到大量的调试、测试、开发等任务，是非常繁琐的，你往往需要开启多个命令行窗口，多个Vs Code窗口，以及浏览器里成吨的标签页来完成这些任务。随着时间进行，你的电脑很快就会变得杂乱不堪。我们需要对这些任务进行整理。我认为可以这么理解，我们每个人也都像一个大语言模型一样，有一个maximum_tokens参数，随着你打开的窗口越来越多，输入的命令越来越多，这些新加进来的东西达到了maximum_tokens之后，你会逐渐忘记前面已经做过的工作，然后你又要花费O(N)的时间去找出之前在哪里看到过的某个什么东西（这个N或许是你打开的所有标签页、窗口数以及命令行窗口里长长的历史消息之和）。你总共需要K步来完成你的任务，从某个时候开始，你像一个滑动窗口一样不断遗忘之前做过的事，导致总体来说你完成这项任务的时间复杂度是O(K·N)。而文档就像是为你这个大模型准备的一个summary，它不断地提取重要的信息记录下来，随后你就不需要重新搜索那么多窗口了，在这个summary里就保存了你需要知道的之前已经习得的任务，所以你的复杂度就降低为O(K)了，工作效率得到大幅提升。
文档的第三个作用是帮助你快速地应对各种汇报要求。这其实算是提高工作效率的一部分，但因为它非常重要，也很有吸引力，所以我将它列为一个单独的作用。正如著名YouTube博主Ali Abdaal在分享自己制作视频思路中所说“Document - don’t create”，凭空创造是很难的，而记录是相对容易的。不断从记录中提炼适合分享的内容才能保证你的创作源泉不枯竭。你几乎总是无法预计，某天你的主管突然心血来潮希望你做一个分享，时间可能从十分钟到一个小时不等 —— 如果这时候你没有足够多的文档记录，需要凭空现做，那天知道你需要多少时间准备。我们后面会介绍“像内容创作者(Content Creator)一样思考”的心理建设，你会了解到，制作优秀的内容是很不容易的（比如让其他人愿意花费十分钟看完的视频/文章，可能需要十个小时甚至更久的时间准备）。当然也不用太担心，如果在平日里你不断地记录，积累足够多的内容，最后汇报的时候只是做一个整合工作，那不会花费太久的时间。你可能不太相信这种记录的力量，我来举一个例子。计算机专业的PhD学生总是在毕业前需要完成一个上百页的毕业论文。从我身边的例子来看，很少有人是早早开始写毕业论文的，一般都是到最后半年，甚至最后一学期才新建这个名为毕业论文的Overleaf文档。但因为大部分人都早已有数篇经过同行评审(peer-reviewed)的已发表的会议或者期刊论文，真正写毕业论文的时候其实只是一个整合、拼接的工作，所以我自己甚至只花费了不到一周的时间就完成了毕业论文的撰写，当然之后还需要一段时间的沟通、修改和迭代。如果是从零开始写这样一个大部头的作品，首先你极不可能坚持写完，其次你很难按时完成，再次你完成了以后还很可能通不过，那真就是匆匆忙忙，连滚带爬了。
2. 像内容创作者一样思考
“发表出来的东西是冰山一角，为了露出这一角给大家看到，你需要构建整座冰山。”
如果你曾经有过内容创作的经验，比如维护YouTube频道，制作抖音视频，持续更新公众号，写知乎文章等，你一定对内容创作的难度深有体会。在一个完全公开的地方创作能让你接触最真实的反馈，当然我知道绝大部分人并没有这样的经历，所以我来介绍一下你必然会经历的历程。
2.1 Nobody cares
每个人或多或少会有一些自我中心主义，因为你通过自己的这个主体来和世界交互、沟通。但很多人没有办法意识到，或者不愿意承认，你的工作、生活乃至各种言论、个人观点对其他人来说是无足轻重的。你可能费尽心力，努力准备了一个自己认为很优质的视频或者文章，字斟句酌，各种剪辑，放到网上，过了几天一看，压根儿就没几个播放量或者阅读量。这太正常不过了，因为“Nobody cares about what you think”，除非你的内容对他们有帮助，比如能带给他们娱乐，带给他们知识，或者是其他什么有价值的东西，哪怕是成为他们的笑料。这一点可能很让人沮丧，但同时也给我们提供了一个比较自由和安全的表达空间。因为没有人关心你写了什么内容，你首先只需要考虑这个内容对你自己有没有用，如果有用就值得创作。值得庆幸的是，在技术领域，如果你的这篇文档能帮到你自己，它也极有可能帮到其他人。所以如果你觉得你的文档能帮到至少另外一个人，你就可以把它发表出来。
2.2 Attention is all you need
借用一下transformer论文的标题，”Attention is all you need”在写作文档和内容创作时是一个很重要的参考意见。获取读者、听众的注意力是一件极其困难的事情，值得我们竭尽全力去做到这一点 —— 当然这里说的注意力是他们自愿的注意力，不是什么领导讲话，有人安排了很多观众不得不听的这种场景。非内容创作者对一个优质内容创作需要花费的时间总是低估的，他们总是以消费者视角去看待一个内容。一个比较极端的例子就是公映的电影，通常放映时间只有两个小时左右，但是公众对这两个小时所需要耗费的人力、财力、时间是没有概念的，所以哪怕你花费了一万个小时去做这个电影，但没有做到大众的心理预期，观众也是不买账的。另外一个经典的例子是单依纯在《我爱你中国》这首合唱里的两句歌词封神名场面。虽然只有两句词，要唱的观众满意，却需要多年的训练和积累，再配合她极高的天赋，正所谓“台上一分钟，台下十年功”。牛顿三定律现在每个中学生花个几节物理课时间就学得滚瓜烂熟，而当年牛顿发现万有引力，创作《自然哲学的数学原理》发明微积分可是用了将近二十年时间（大概从1665年到1687年最终出版）。这样的例子数不胜数，写文档也是一样，一个优秀的文档通常是在你踩过各种坑，克服各种困难以后总结出来的精华，别人阅读也许就十几二十分钟，但它的构建可能会花费你好几个小时，甚至好几天的时间。我说这些不是想吓得大家不敢写文档了，而是希望为各位树立一个心理预期 —— 创作一个好作品是需要时间的，做一次好的分享也没有那么简单，我们需要花费足够多的时间给别人带来切实的价值，才能获得这难能可贵的注意力。
2.3 Document, don’t create
Ali Abdaal说的这一点”Document, don’t create”我觉得很受用，所有的创作都是你的Summary功能，发表出来的东西是冰山一角，为了露出这一角给大家看到，你需要构建整座冰山。这句话也是一种方法论，鲜有人能通过”create”的方法源源不断地创作，但”document”却是每个人都可以坚持完成的。我相信有人看到这里，突然开始才思泉涌，觉得自己的灵感不可能枯竭，这是一个好征兆，可以先开始写起来了！然而，这个世界上最难的事情就是坚持不懈(Consistency)，很多人在人生的某一个时刻都或许会突然才思泉涌，突然感觉要开始每天坚持拍Vlog，或者每天坚持拍一张照片，或者哪怕是每天坚持养一下多邻国的小鸟，只有极少数的人能坚持一年，更少的人能一直坚持下去。内容创作的核心就是Consistency，你必须不断地创作，不因为任何原因随意间断 —— 也有人说这是一种习惯，就像健身、弹琴、画画等等需要很多年才能练成的技能都需要这个东西。而达成Consistency的一个方法就是记录，而非创造。
3. 文档的坏味道
Martin Fowler在《重构：改善既有代码设计》一书中介绍了“代码的坏味道”，对于每一个需要写代码的人来说都有很大的帮助；我想文档也是有类似的坏味道可以总结的，但又因为我暂时没有那么大的精力和时间去写一整本书，我先谈谈几个常见的我发现的文档的坏味道供大家参考。
3.1 标准而枯燥乏味的文字 (Standardized boring words)
很多现有的技术文档喜欢使用一种类似“使用说明书”的文体进行编写，它们通常是由客户或者领导的需求推动的，而不是开发者自发撰写的。写文档的人被安排了这个工作，他们自己也不知道为什么要写这个文档，只想尽快交差，甚至写完的文档自己都不想再看一眼。他们习惯于用一些很枯燥的文字介绍本来就枯燥乏味的技术内容，让人看得直打瞌睡。我建议每个技术人员有时间都去看一看曹天元写的书《上帝掷骰子吗？量子物理史话》，你会了解到哪怕是介绍量子物理的发展史，整个故事同样可以生动有趣、引人入胜。可能是因为应试化教育的训练，有好多人对标准而毫无个性的词汇、语句有着很深的执念，仿佛只要文字中透露出一点点“这段话是活人写的”的特征，就会让整个技术文档丧失专业性。如果随便找几本大师写的技术丛书，比如Martin Fowler的《Refactoring: Improving the Design of Existing Code》、Bruce Eckel的《Thinking in C++》、Gilbert Strang的《Introduction to Linear Algebra》等等，你都会感受到作者在和你像朋友一样对话，顺便就教会了你专业的技术知识。为什么我举的例子都是英文书籍呢，我确实是想找一本中文专业书，但想来想去好像还是曹天元的《上帝掷骰子吗？》写得好。我本科也学过《数学分析》、《线性代数》、《常微分方程》等等，但很不幸，这些国内的权威教材都落入了我总结的“文档的坏味道”范畴，它们无一例外都拥有标准而枯燥乏味的文字。
3.2 专业术语堆叠 (Too many jargons)
基于相似的原因，这类“使用说明书”文体的文档，还往往喜欢使用一堆人类看不懂的专业术语。它们诞生之初就不是以教学为目的的，而是为了彰显自己的专业性，仿佛术语越晦涩，懂的人越少，写文档的人地位就越高。有时候这是一种自卑，因为他的技术实力可能并不足以支撑他的地位，所以他不得不想出一些并不重要的东西彰显自己的学识。当然也不排除另外一些初学者，他们学习的时候看的就是这类文档，学会了很多专业术语，但他们也不明白到底是什么意思，只是依葫芦画瓢，继续把这些术语传承下去。好的文档绝对不是只有这个领域的顶级专家才能看懂，我们的终极追求是“你妈也能看懂你的文档”，但很多时候技术过于复杂，很难简化到这种程度，但我们的文档至少应该达到同事们都能无痛浏览的程度。技术文档，永远是把复杂的问题简化，而不是把简单的问题复杂化。