人脑会自动填补记忆中的空白，但有时候并不准确。

你可能还记得大富翁游戏中的垄断先生戴着单片眼镜。或者你觉得“伯恩斯坦熊”应该拼写成“伯恩斯坦恩熊”。

都不是真的。

曼德拉效应就是这样：当一群人以同样的方式记住某件事，但实际上实际上是错误的。这不仅仅是遗忘，这是虚假记忆。它发生的原因是我们的大脑会填补空白，重复错误，甚至假设不存在的细节。

在工程中，我们也会这样做。不是用老式眼镜或这样的儿童读物，而是用一些工具和方法。

• 代码，
• 系统，
• 流程，
• 或决策，

我们以为记得某件事情是如何运作，直到我们搞不清楚为止。

问一个开发者一段旧代码，他们通常会说：“是的，我记得这段代码是怎么运行的。”

但当他们再看时，他们可能不会那么在意了。这很人性。我们的记忆力也就这样，特别是每天要处理那么多信息的时候。

一群工程师很难想象出一个从未存在过的功能。但细节会逐渐模糊，假设也不一定总是正确的。

这不仅仅是记忆失误——它变成了一个真正的工程难题。团队继续前行，项目逐渐扩大，原本明确的事项很容易变成猜测。代码文档本应避免这种情况，但常不完整、过时，甚至完全没留下。

作为工程经理（EM），你不一定亲自编写所有代码。但你得确保你的团队能够理解、维护和在此基础上开发。这就是为什么文档不是可选的，也不是仅仅一个“锦上添花”的功能。它是战略性和高度人性化的必需品。

有时候，你不知道怎么去理解一个难懂的过程、一个模糊的变量，或者是处理一团糟的服务。

当这种情况出现时，好的文档就像你的救命稻草一样重要。

• 消除疑惑
• 节省时间
• 让项目持续推进，请点击这里了解更多信息：点击这里了解更多信息

没有它，你只能靠猜测、翻找代码和依赖记忆。这只会浪费时间，减缓进度。

文档帮助团队保持方向。它记录了他们构建的内容及背后的决策原因。它描绘出复杂系统的架构，并保留关键决策，让未来的工作更加顺利和高效。

想象一下开始新工作时完全没有指导。也许你之前也经历过这种情况。没有介绍，没有解释。只有一堆代码，时间紧迫，还期望你能搞清楚。这就是没有适当文档指导的新员工入职状态。

实际上，新工程师不需要感到迷茫或手足无措。好的文档可以成为他们的导航工具。

不用老是不停地请求同事帮忙，新来的员工可以做其他事情：

• 看看系统中所有部分是如何相互连接的
• 理解已定决策背后的原因
• 并且更快地熟悉起来，不再需要持续的帮助

但入职只是拼图中的一个小环节。文档对每个人来说都很有用。它防止知识丢失，使交接更方便，并能让团队合作更顺畅。

这不仅仅是便利的问题。它让知识留在团队手里，而不是困在某个人的脑子里。

要是你够幸运，你的团队里会有那么一个人是“社交粘合剂”。这个人会组织庆祝日、关心同事的状态，并保持团队精神。他们帮助建立强大的团队联系。

文档在技术上扮演着类似的角色。就像社交纽带连接人们一样，文档将团队的知识串联起来。

这不仅仅是为了一个团队。文档将工程中不同的角色连接起来，包括：

• 前端
• 后端
• 设计
• QA
• 等

每个角色都有助于构建和维护复杂的系统。当文档完善时，它能把团队紧紧地绑在一起。而缺少文档时，一切都将分崩离析。

这就为什么:

它帮助大家理解系统各个部分是如何相互连接的。而不是依赖于别的东西：

• 零散的消息
• 会议（查看会议详情）
• 以及口耳相传

团队可以利用清晰的文档来说明流程、API 以及架构选择。

例如，前端开发人员不应该去瞎猜API是如何工作的。他们应该有清楚的文档说明。同样，质量保证工程师也需要明确的行为预期和测试用例说明。

文档不仅是办公室团队的支柱。比如说，远程团队依赖书面沟通，而是更倾向于书面沟通，而不是快速的面对面交流。

没有文档，知识就难以及时共享。如果缺少关键细节，新员工会迷失方向，错误频出，工作效率也会大大降低。

一个有详细记录的系统可以让团队成员们：

• 无需等待答案就能理解流程
• 异步工作，同时保持目标一致
• 快速融入，尽早开始贡献

每个工程团队都有其独特的流程、最佳实践和编码规范。共享文档有助于在整个公司内贯彻这些标准，例如：确保，

• 代码审查也遵循相同的原则
• 开发环境也是一致的
• 特性的发布也遵循结构化的流程

如果没有共享的文档，每个团队都会按照自己的方式做事。这会导致不一致、低效以及沟通障碍。

写文档不只是为了记录以免忘掉，更重要的是：

• 保持团队之间的联系
• 减少摩擦点
• 确保不同角色、地点和项目之间的顺畅合作

让我们面对现实，编写文档确实很费时间。这也是为什么它常常被忽略的原因之一。但是，AI 工具正在改变这一情况。AI 可以根据代码注释和结构自动生成和更新文档。

像 Cursor 这样的工具会扫描代码并自动生成文档，依据函数名称、参数及注释。这使得文档始终更新，而团队无需额外付出努力。即使代码被重构，文档也能保持准确。

这只是文档中的一小部分。其他格式，如会议记录、Slack 对话和 Jira 中的评论，也可以被转换成文档。

比如说，你想给你的应用程序增加一个新服务。有了合适的文档和标准，AI工具可以自动帮你编写这个服务。同样，它们还会自动生成新服务的文档。

AI工具还能让文档变得更棒。

• 填补知识空白： 它们保持文档结构化、准确且易于查找，填补知识空白。
• 维护团队间的一致性： AI通常遵循标准结构，这使得团队间文档一致性得以维持。
• 减少错误和过时信息： AI发现缺失的细节和不一致之处，帮助团队保持文档的准确性。

有了自动更新，文档就能保持最新。工程师可以信任他们所读的内容，并且花费更少的时间去质疑。AI工具让工程师摆脱了重复和手动更新的繁琐工作，让他们可以专注于更有意义的任务。

这确实很难，但你可以参考一些指导原则。

过多的文档可能会让人感到压倒性。冗长复杂的文档会让人们快速翻阅内容，忽略细节或直接跳过。

文档不足同样会带来问题，缺少说明可能导致假设。假设可能会导致错误。

最好的方法是保持文档简洁、清晰且易于搜索，而不是写大量的文档，而是专注于团队真正需要的内容。

尽量保留你的文档。

• 简洁：只关注最重要的细节
• 有条理：使用标题、项目符号和简短的段落
• 容易找到：例如Markdown文件、Google文档或维基，这些都是存储它的工具

记得，好的文档应在问题提出之前就解答疑问。它应该引导工程师，而不需要让他们翻阅无数页。共享知识应该是一个有用的工具，而不是负担。

人的记忆力不是百分之百准确的；工程也很复杂；文档就是把这些点连接起来的桥梁。

没有它，团队依赖于记忆和分散的消息，以及无休止的会议。这会导致混乱、延误和错误的发生。良好的文档是一个中心的信息来源。它确保团队保持连接和高效运转，并有助于：

• 入职引导：新工程师可以快速理解系统，无需依赖他人
• 协作：不同角色（前端、后端、QA、设计师）可以顺畅地合作
• 远程和分布式工作：书面文档使得团队成员可以异步协作
• 一致性：共享文档确保各个团队能够遵循最佳实践

作为一名工程经理（EM），你定下了基调。如果你的团队看到你记录决策和最佳实践，并让这些知识变得可见——他们也会跟从你的做法。而如果你觉得文档工作很麻烦，他们也会这么想。

AI 正在改变文档编写。它自动更新内容，从代码自动生成文档，并确保文档一致性，减轻了负担，让文档编写更轻松。

用简单的工具让它简单些。通过展示它如何省时和减少错误来突出其价值。把它变成习惯，而不是任务。

如果你觉得这些内容有用，可以订阅我的通讯。
[MCP]：模型上下文协议 (Model Context Protocol)
[LLM]：大型语言模型 (Large Language Model)
[RAG]：检索增强生成 (Retrieval-Augmented Generation)
[SSE]：服务器发送事件 (Server-Sent Events)