引言

博主在工作中发现一个有意思的矛盾现象：每个人都同意把文档写好非常重要，但似乎大部分人都比较抗拒去写文档，或者写的文档比较敷衍，缺少很多关键信息。

注意，这里的“文档”指的不是像博客一样的文章，而是工作中用到的如技术方案、工作计划、复盘总结之类的材料，主要用来方便跟同事或者上级沟通，或留下记录。

这是不是让你想起了一句程序员间流传的老话：我讨厌两种人，一种是不写注释的人，一种是让我写注释的人。

本人还算写了不少文档，也积累了一定的经验，这篇文章主要是分享一些自己在工作中写文档的感悟，是一篇杂谈，而不是怎么写文档的方法论，文章的内容包括但不限于：

• 分析为什么写好文档很重要，但大部分人都不喜欢写文档
• 引申——如何驱动自己，培养做事情的习惯
• 一些关于写文档的小tips

正文

写好文档真的重要吗

先说结论：不一定，需要结合当下情况与长期考虑。

不知道各位有没有遇到过这样的情况：

• 场景一：接手了公司的某个项目，一看相关文档简直一团乱麻，想要知道项目信息（比如某个功能点的需求背景）需要在多个文档间反复横跳，甚至可能根本找不到信息，只能去找之前的负责人问，然后被各种“踢皮球”
• 场景二：接手了某个离职同事的项目代码，发现在经过了n轮测试迭代之后，原先的技术方案跟代码逻辑可以说毫无关系，代码也基本没有注释，只能硬着头皮搞“逆向工程”理清逻辑，进而导致项目的新任务延期

看了上面的场景，相信各位也意识到为什么需要写好文档了，个人认为重要性主要体现在以下几点：

• 知识留存与传承，缩短上手周期
• 提升协作效率，减少沟通摩擦
• 保证信息的可追溯性

但在场景二中，我们也能发现一个问题：过时的文档有可能是无用的。

那么，写文档解决了什么问题？它的本质是什么？

我自己的理解是——文档的本质是投入前期的时间成本，减少后期的时间成本，前期投入的文档写作时间，会在未来的协作、维护和扩展中节约成倍的时间。

说到这里，上面的结论就很好理解了，写好文档确实是重要的，但需要考虑文档在未来的工作中能不能起到减少时间成本的作用。

文档困境

鲁迅曾经说过：写一篇好的文档看似困难，实际上并不简单

那么写文档到底难在哪呢，个人的感受如下：

• 将复杂的概念和流程清晰地表达出来，对许多人来说是一个不小的挑战，需要投入大量时间来理清逻辑
• 许多人在技术上很强，但可能缺乏编写文档的技能和经验，导致不知道该写什么，或者写不出重点
• 编写文档通常需要投入大量时间和精力，但往往与其他更紧急的任务发生冲突

可以发现，除了最后一点之外，其他的都是经验问题，那么解决方法就也明确了：多写，积累经验

此时可能你已经想到了这个经典表情包：

接下来，就是关于写文档的终极问题：怎么才能做到多写？

试着驱动自己

微习惯 & 内在驱动力

可能有朋友已经发现了，不仅仅是写文档，大部分事情想做好其实都需要我们多做，培养习惯，然后熟能生巧。

那么具体该怎么做呢？

这里博主推荐两本书：《微习惯》 和 《内在驱动力》。

简单介绍下概念：

• 微习惯：指一些非常小、简单到几乎无法拒绝的行为习惯，核心思想是通过设定微小的、容易完成的目标，逐步培养长期的积极习惯，从而实现持续的行为改变
• 内在驱动力：指个体由于内在的兴趣、享受或满足感而自发进行某种活动的动力，而不是因为外部的奖励或压力。内在驱动力源于个体对活动本身的热爱、好奇心和挑战感，表现为在没有外部奖励的情况下仍然愿意花时间和精力去完成某项任务

这里还有一个概念叫做“内化（Internalization）”，在心理学和行为科学中，指的是将外在的行为、规则或价值观转化为个体内在的、自发的需求或认同的过程。在养成习惯的语境下，“内化期”意味着让行为从“刻意坚持”转变为“自然需求”，甚至成为自我身份的一部分

一个示例

结合上面这的概念，以培养写博客的习惯为例，这里给出一个示例，各位可以参考：

首先，将写博客这件事分为三个时期：

• 启动期——用微习惯降低刚开始的阻力
• 适应期——寻找内在价值
• 内化期——依赖内在驱动力

然后，制定每个时期的目标和具体步骤（天数不重要，按自己喜欢节奏即可）

启动期（第1-7天）：

• 目标：让写博客成为每天无压力的习惯动作
• 步骤：
  1. 设定微习惯：每天完成以下任一动作（五分钟内即可）
     • 记录一个灵感碎片，比如突然想到的话题或对自己有启发的句子
     • 打开博客编辑器，任意写一句话
  2. 挖掘内在动力：
     • 完成动作后思考：今天的写作让我有了什么新想法？

适应期（第8-21天）：

• 目标：从“完成任务”转向“享受过程”，找到写作对自己的意义
• 步骤：
  1. 升级微习惯（约5-10分钟）
     • 每天写100字，状态好时自由发挥
  2. 激活内在动力
     • 每周末来一次“价值回顾”：本周哪次写作让我感到愉悦？为什么？
  3. 建立正向反馈
     • 向身边的人分享自己的写作内容，或自我奖励

内化期（22天以后）：

• 目标：让写作从“习惯”变为“需求”，形成自我认同
• 步骤：
  1. 调整习惯
     • 从字数限制调整为每天为博客投入15分钟（写作/修改/找灵感均可）
     • 避免完美主义，允许自己跳过1-2天
  2. 深化内在动力
     • 探索兴趣方向，尝试不同写作风格，记录哪种类型是自己最投入的
     • 想象未来——有人可能因为我的某篇文章而受益

最后，可以通过下面的方法判断自己是否已经内化了写作的习惯：

• 启动写作时无需挣扎，像吃饭一样自然
• 偶尔中断后不会焦虑，而是想主动补上
• 向别人介绍时，可以自然地说“我平时喜欢写博客”

几个小技巧

博主写了不少文档，自然也是积累了一些技巧的，下面就分享给各位

以减少阅读时间为目标

通常来说，我们希望尽可能快的获取一篇文档包含的主要信息，一昧的信息量堆叠（比如一大段文字）往往让人看了就犯困

因此，我们需要想清楚哪些信息是重要且一定要传达给读者的，然后想办法突出这些信息

个人常用以下几种方法：

• 加粗字体
• 换个颜色
• 【这里很重要】直接标明重要部分

当写完一篇文档后，从头开始，只读突出信息的部分，看这些部分是否已经包含了所有主要内容，这样可以判断出文档是否能够传达重要信息。

一图胜千言

我们的大脑从图片获取信息的速度是比文字快非常多的，所以当需要表达信息密度很大的内容时，可以想办法将其用图片的形式展示出来，比如经典的MVC架构：

可以试着自己用文字描述一下图片表达的内容，你会发现用图片来描述简直太方便了（当然，将文字提炼为图片也不是一个容易的过程）

适当留白

在适当的地方留白有利于引发读者思考（但不要大段留白，不然的话）

总结

• 写好文档不是一件容易的事，它是前期与后期的时间成本交换。
• 我们可以利用微习惯与内在驱动力来养成习惯，进而把事情做好