前言

个人非常喜欢文档编写, 仅次于写代码.

爱好以外, 文档更是一种需要, 文档为团队带来了长期价值.

任何人每投入一小时的文档编写，都能为整个项目节省100小时的生产力.

首先, 文档消除了猜测和重复发明轮子的问题, 任何多人参与的项目都是一座迷宫, 文档是我们的地图, 让我们自由的穿梭其中.

老手可以通过这张图加深项目/技术的理解, 不断完善细节, 最后做到得心应手, 迷宫变成乐园.

新手会更快地找到立足之地，更早的成为项目的贡献者，并且比我们期望的更高效工作.

不要像这样做⬆️

文档也很好的解决团队内部沟通的问题, 以下两种沟通方式都同样典型, 我们应改选哪种?

• 发微信/拉个群，零零散散的问问, 要求他们解释函数/类/代码.
• 自己查找必要的信息, 在文档系统中描述遇到的问题, 自己的思考过程, 开给对方, 让他以自己的节奏处理.

答案: 2, 永远是2!

个人的文档体验

想象一下，我是一家初创企业的技术创始人, 正淹没在混乱之中(是呀, 还能咋样呢). 每天都在玩打地鼠游戏，每次只是试图在被拖入另一个问题之前稍微恢复一口气.

如何摆脱这种恶性循环? 文档是其中一个答案.

文档, 不仅仅是指维护一个简单的操作手册或记录会议纪要这么简单, 我们要建立一种知识不仅局限于个人而是散布并为整个组织所能访问的文化.

任何一件不记录下来的事情都等于将来的资源浪费，必定会带来麻烦.

对于任何人来说, 最好的麻烦从来是不需要他去解决的麻烦.

对于一个需要知识和技能来组织的软件公司, 文档建立起的传承体系可以

见之于未萌，识之于未发

也就是说, 从源头解决问题, 再说回个人依赖, 团队里某个人不可或缺是典型的巴士因子

是一不可持续, 且不健康的.

善战者无赫赫之功

要构建能够在没有个人强依赖的的系统.

最后说下文档和思考的关系, 文档是思考的媒体.

第一时间出现在脑中的问题，必然是一个不成熟的问题, 这个问题需要进一步的思考, 需要提供更多的信息.

处于婴儿期问题出现在我的眼前, 意味着我本可以做其他事情的时间要投入到这个不成熟的问题上, 和你一起梳理.

随着企业规模的扩大，人员、项目和复杂性的增加是呈指数级增长的.

知识在头脑中变得封闭，沟通变得复杂，很快，我们花费在交流知识的时间会远远超过实际使用知识的时间.

我开始意识到, 我需要尽一切可能榨取我能够得到的知识，并将其写下来.

文档就会成为共识的来源, 加以积累, 成体系的文档就会成为捕捉和保留集体智慧的知识库.

这个智慧可以帮助团队中的每个人找到各种知道自己不知道的, 和不知道自己不知道的问题的答案.

当然, 这也将使我们每个人能够休假.

先文档, 再开会

已经谈过文档化可以让知识有效的积累和传播，接下来让我们谈谈时间和效率的问题.

时间是最重要的资源. 时钟的每一秒都承载着做出的决策、构建的产品和征服的市场的重量.

而开会却是这种资源的臭名昭著的窃贼. 并不是说所有的会议都是坏的，但我们必须对它们的成本和价值进行批判性审查.

用布科夫斯基的话来说，“除非你从内心深处像火箭一样喷射出来，否则不要做它”，把同样的原则应用于会议--除非有必要，否则不要开会.

频繁召开会议的不断需要是一个更深层次问题的症状——缺乏明确、可访问和可靠的文档.

一个良好记录的工作流程不需要一个长达一小时的会议来进行澄清. 一个经过良好记录的决策不需要一个满屋子的人来理解其基本原理. 一个良好记录的知识库不需要每当新成员加入团队时都要进行一次团队会.

“但会议不是沟通的重要手段吗？”是的，它们是. 但是，太多的会议，尤其是管理不善的会议，会让我们陷入瘫痪.

它们营造了生产力的幻觉，而实际上却抑制了生产力. 通过减少对会议的依赖, 强调以文档为先的异步沟通，你可以让你的团队在不受会议束缚的情况下有效地进行沟通.

想一想：每次不必要的会议都是机会成本的损失, 想想本可以改进重要的算法，想想本可以获得的一些时间放松自己，避免过度劳累的休息时间.

从本质上讲，减少对会议的依赖不仅仅是为了节省时间，更是为了重新获得专注、创新和创造的能力——这些都是公司的命脉.

从个人经验出发, 成长是个苦乐参半的过程，在各项活动中, 付出并不总有回报，但是我也向你保证：将时间和资源用于文档编写，而不是开会，效果更好.

大多数会议很容易用一份用心起草的文档来取代，这份文档汇总相关数据, 问题, 附上自己的思考, 建议以及初步的解决方案，然后邀请其他人参与并给出建议.

会议往往会膨胀到无法控制. 本来是召集一次快速的讨论来讨论一个小问题，结果不觉间卷入了关于按钮颜色的两个小时的辩论.

此外，会议往往更偏向于最响亮的声音，而不一定是最好的想法. 这是一种微妙的偏见形式，可能抑制创新和思想的多样性.

而文档则平衡了竞争环境. 它为每个团队成员提供了表达自己思想和见解的平台，无论职位或沟通风格如何. 它倡导思考和反思的文化，而不是匆忙判断和冲动决策.

会议召集应该审慎, 召集全员开一次全公司范围的会议，宣布某某想法, 效果会如何呢? 大概是这样的:

• 不好好准备的会议是浪费大家时间
• 无法自洽的逻辑会让参会人损失信心
• 陷入尴尬境地的时候的努力会显得更加尴尬

陷入这种情况, 取决于主讲人性格, 会不自觉的武断强硬而显得果断, 或者唯唯诺诺四处讨好, 都显得很傻.

将决策和决策过程记录下来等于有了清晰的思路和脉络.

每个决策都是公司不断成长的基石，记录下来可以提供可靠的参考，一种详细说明你的思考过程, 关注点和原理的架构蓝图. 这种清晰度在规模扩大、面临日益复杂的挑战时非常宝贵.

当在决策过程中引入文档时, 它保存着每个决策所带来的上下文, 见解和思考过程.

当类似的情况再次出现时，可以回顾这个知识库, 不断加深自己的思考, 这本身就是一种可持续性的技巧.

应该鼓励团队记录他们的决策过程，澄清假设、推理和预期结果. 让讨论这些记录下来的决策成为会议的标准做法，促进开放反馈和协作决策的文化.

这其中的美妙之处在于，它将每个决策都转化为一个学习机会，培养团队内的成长思维. 它让每个人都能看到过去选择的后果，并理解其中的考虑因素，使他们成为更好的决策者.

建立以文档为先的文化

以文档为先的文化意味着在公司中培养一个共享意识，一个将所有人联系在一起的统一力量.

这不仅仅是对过程的刻板遵循，而是关于民主化知识，打破等级壁垒，培养学习文化.

以文档为先的文化并不意味着每个人都忙于整天编写文档, 只是意味着每个人都认识到文档编写和分享经验的价值.

当然，建立一个项目时，始终将文档作为任何任务的一部分.

应该默认一定比例的员工时间用于记录他们的故事, 这不仅仅是为了效率，而是为了创造一个共享知识被赞赏的环境.

它不仅仅是为了创造产品，而是打造一个故事——一个关于集体成长的故事.

你在其中的角色可以是催化剂和促进者, 始终以身作则.

记录你自己的过程和决策，并公开分享. 随时做笔记, 鼓励反馈和学习的文化，在每个文档上都是讨论、改进和创新的起点.

如果需要做决策，从文档开始，而不是从会议开始. 如果需要讨论利弊，从文档开始.

知识的输出者, 人们会以之为榜样，仿效他们的行为.

知识的接受者, 我们通过鼓励记录工作过程, 学习经验. 会培养他们超越指定角色和任务的拥有权和参与度, 逐渐为公司知识库和成功的积极贡献者.

工具

接下来，我们再谈谈工具, 首先个人的笔记工具, typora, emacs, Notion 选一个(不要word), 学会markdown.

团队文档共享, 不止上百种吧, 我们先用云效.

针对常见的文档类型, 准备模板和指南. 把它们看作是文档的DNA——它们提供了结构、一致性和可预测性，使你的知识能够复制和有效传播.

这是一个复杂且耗时的任务，但一旦你拥有了它们，就会变得更容易.

模板确保以标准化的格式记录信息，使其易于理解和比较. 另一方面，指南提供了“游戏规则”，确保每个人都知道应该记录什么、如何记录以及在哪里找到.

创建清单，启动审查流程，并建立版本控制. 这些工具不是束缚，它们帮助你的文档以一个声音、一个口吻和一个风格说话.

将文档作为公司价值观的一部分. 鼓励团队将其视为工作的一部分，与编写代码一样重要. 将其作为绩效评估和反馈会议的例行工作. 要求他们改进它，并要求他们找出你的流程中的缺陷.

随着公司发展，它的文档需求也会发生变化.

反对意见

并不是每个人都会喜欢文档. 特别我们还是一家成立几年的初创公司，肯定会遇到一些反对意见. 大家的舒适区和犹豫与任何技术问题一样真实, 需要用同样的耐心来解决.

我想这个问题应该跟多的通过参与来解决, 建立交流渠道, 理解他们的观点, 并解决他们的疑惑和困难.

向大家展示文档为先的文化可以带来的好处, 效率和自由.

为那些采用这种文化的人庆祝——他们的成功、努力和向以文档为先的方法迈出的步伐, 这不仅是对个人鼓励，我们也期待更多后来者.

“不是每个人都会喜欢它”其实还是个小问题.

文档本身也不会是完美的吗, 一开始可能会很糟糕. 没关系, 不要惊慌.

记住，它是一个需要时间发展的有机体.

作为倡导者，我的角色是确保文档的质量随着时间的推移而提高, 这不是关于监管，而是关于培养.

好处

这更多是我个人对好的文档样式的思考.

首先, 清晰和简明: 它是将复杂概念分解为易于理解的部分, 削减冗余, 专注于重要内容. 你的文档不是一部冗长的小说，而是别人需要遵循的指南.

• 例如，可以以不同的方式强调信息
• 如果感觉太干燥，需要重写
• 添加插图和视频解释.

然后是结构和组织, 我需要一个有意义, 直观的格式. 如果人们找不到他们正在寻找的内容，他们会迷失和沮丧, 我们的文档需要引导他们，而不是使他们困惑.

• 将其分解成不同文章, 并进行交叉链接相关文档.
• 构建索引结构.
• 上一篇/下一篇-建议哪些其他文档可能有帮助.

接下来是可访问性和可发现性. 你的文档不是藏在尘土飞扬的老图书馆中的秘密文献. 它是一个活生生的资源，需要易于访问和发现.

• 利用标签和分类，将信息分成不同的群组.
• 利用全文搜索

最后, 也是至关重要的, 我们的文档不是一个纪念碑. 它不是一次性建立然后忘记的东西. 它是一个不断发展, 不断演化的实体, 需要定期更新和维护.

• 组织会发生变化，你的知识会扩展，文档需要反映这一点
• 跟踪最后更改的日期，并更新那些超过一年的日期
• 跟踪此信息的所有者，并定期更新

没有灵丹妙药

我已经为文档和写作唱了一整篇赞歌, 感谢你读到这里.

让我停下来一分钟: 文档虽然非常非常重要, 但并不是一个银弹.

它不会像盖世英雄一样，身披黄金展架脚踏七彩祥云, 救我们于水火, 它只是一个工具.

像任何工具一样，它也有局限性, 你仍然会遇到问题…但会少一些.

文档虽然有助于协作，但不能替代人与人之间的互动.

它无法复制面对面沟通的微妙之处，即时反馈的价值，或者团队一起解决棘手问题时建立的联系.

这些会议或者甚至非正式的碰头会议中建立的友情对于培养健康的工作文化和推动团队动力至关重要.

如果你用一系列文档代替了所有的人际互动，那么你就让你的团队陷入孤立和脱离的境地，这是低参与度的通行证.

编写文档本身可能是耗时的. 写出实用、简明和易于理解的文档需要思考, 思维清晰和简化的技巧.

有人可能会说，用于编写这些文档的时间可以更好地用于其他地方. 他们并不完全错, 如果你记录每一个细节, 会有一个庞大的信息库, 难以导航, 可能并不那么有用.

我们都见识过, 很多校长一上午的讲话，完全可以归纳为一句, 过度文档化就像这样.

最后, 尽管尽力了，文档很快就会过时.

技术不断发展，流程不断变化，一个月前相关的东西可能今天已经不相关了.

结论

对于所有同事、未来的工程管理人员和CTO们，我的建议很简单：培养对文档的热爱.

你可能把它视为一项琐事, 一项事后思考的事情或者一种麻烦. 但请相信我, 文档不仅仅是你待办事项清单上的一项任务. 它是成功的支柱，是连接思想, 人员和愿景的桥梁. 把它视为一种学习、分享和创造影响的机会，而不是负担.

• 从小处开始, 但从今天开始. 不要等待一个宏大的战略或完美的工具
• 从记录你的代码、决策和学习开始
• 让它成为你日常工作流程的一部分，而不是一天结束时的任务

希望随着你前进，将这种文档优先的文化融入团队, 项目和组织中.