老子写个代码而已，凭什么还要我写文档？

前段时间，我们团队在做 鱼聪明 AI 项目时，2 名开发同学竟然因为 “写文档” 吵起来了。

开发 A：这个项目是敏捷开发，我得赶紧写代码、快速上线，哪有空写文档？

开发 B：你不写文档，很多业务信息我就不了解，出了问题你背锅？！

开发 A：我给你讲一遍就完了，写文档多麻烦？大不了你把我的话记到文档上！

开发 B：你厉害，我给你竖大拇哥 👍🏻

。。。

作为一名经常写文档、并且认为写文档至关重要的程序员，听到他们的友好交流后，我决定要写下这篇文章 ——  分享写文档的经验和方法。因为我认为，无论是个人还是团队，无论是在学习、工作、还是项目中，无论对程序员、产品经理、还是项目管理者，做好文档沉淀都是至关重要的。我也真心希望未来和我合作的同事，不要把项目的信息和代码口口相传，而是能够做好分类整理，让大家高效协作。

下面我会给大家依次分享：为什么要写文档？怎么写出好文档？怎么管理好文档？

什么是文档？

文档是记录、储存和传递信息的载体。

我们的项目需求表、系统的设计方案、某某调研报告、某次会议记录、解决过的 Bug，甚至是学某个视频教程时随手记录的笔记，都是文档。

为什么要写文档？

从文档的定义出发，我们就已经能意识到文档的基本作用了。

• 记录信息：收集临时的信息
• 储存信息：防止信息丢失和遗忘
• 传递信息：把信息和他人共享

我们的人脑容量有限，不可能记忆所有信息，而写文档，本质上就是在打造属于我们的第二大脑。

像我的脑容量是比较小的，所以我有随手记录、随手写文档的习惯，有的时候走在路上有个好点子都立刻掏出手机记下来。

文档对项目的价值

而对于做项目（尤其是企业大项目），文档又有更进一步的价值。

在项目初期，文档具有指导整个项目顺利推进的意义。如果将做项目比作盖摩天大楼，那么文档就是大楼的蓝图。没有蓝图，建筑工人只能盲目工作，能不能完成都很难说，更别提保证大楼的质量和安全了。

同样，在项目初期不写文档、没有系统的方案和执行计划，团队成员在开发过程中就会迷失方向，会经常出现延期、完不成、返工的情况。

在项目中期，文档的意义是持续记录和追踪项目的状态，让信息在团队间公开透明，从而做出正确的选择、即时规避风险。

打个比方，把做项目当成跑马拉松，文档就是沿途的路标，会告诉大家跑到哪里了、接下来怎么跑；而如果前方有危险，路标也会给大家警示。如果没有文档，大家很快就跑散了，各自为战；一个人遭遇了风险，可能会拖垮整个团队。

在项目后期，文档的意义是帮助我们复盘总结、持续维护项目以及知识传承。

• 复盘总结：通过阅读文档，我们能够回顾整个项目从诞生到结束的完整过程，从而分析出该项目成功或失败的原因，便于我们从中吸取经验，助力下一个项目的成功。

• 持续维护项目：如果这是一个需要持续维护和更新的项目，有了文档（比如 Bug 手册、用户手册），项目出现问题时，哪怕换了一位项目维护者，也能很快地从文档中找到解决方案，不会出现 “一人离职、项目倒闭” 的情况。

• 知识传承：沉淀好的文档，是前人宝贵的经验、教训、思路和方法汇总，非常值得学习，未来能给更多团队的同学带来启发和收获。

总之，写文档是一件利人利己的事，每写一个字，都是在生产价值。

在理解了文档的重要性后，我们应该怎么做好文档沉淀呢？

这里我们把文档沉淀进行拆分，需要做好两件事：

1. 写出好文档（这是前提）
2. 管理好文档

下面我们分别讲解。

怎么写出好文档？

想要写出好的文档，我们要先了解 “什么是好文档”，然后再去学习写文档的工具和方法。

什么是好文档？

我自己评判文档好坏的几个标准：

1）人能看懂、易于理解的

首先，你的文档是给人看的，如果是自己记录学习笔记，那么首先要保证自己能看懂；如果是在团队内共享文档，那么要保证别人能理解。如果本来一句话就能说清楚的内容，你在文档上用 20 句话来解释，这样哪怕你写了文档，别人可能还是直接来麻烦你本人。

2）结构清晰、易于查找的

好的文档，应该是别人从上到下扫一遍，就知道你在写什么、你想表达什么、我能从你的文档中得到什么、我在哪能找到我需要的内容。

就像这篇文章一样，我用了多级标题来划分文章的结构，你能直接通过目录大纲快速定位感兴趣的内容进行阅读。

3）内容完整、表述准确的

好的文档就像是项目中的一个模块，它应该是完整的、高内聚的，让人仅通过这个文档，就能解决自己的问题。

比如《某 Java Bug 的解决方案》文档，应该把 Bug 的起因、分析排查过程、解决方案、经验总结全部写出来。而不是说把这个 Bug 抛出来，怎么解决我不说~ 哎，就是玩~

另外，文档中的一些词汇和语句的表述一定要尽量准确，不能有歧义！

比如我们鱼聪明 AI 在最初评估成本时，写的是 “服务器若干、价格累积万元左右”，“若干” 和 “万元左右” 其实都是比较模糊的词汇，类似的情况多了就可能导致成本计算错误而亏损。后面我们把上述词汇改成了类似 “服务器 4C 8G 1 台，价格 1000 元 / 月”，实现更精细化的成本控制。

此外，好文档还可能有其他的标准，比如面向用户的产品文档，应该保证文档整体的风格、排版一致，给读者带来最佳的体验。文档写得好，也会提升用户对团队的认可度，从而更愿意使用团队的产品。

写作工具

工欲善其事必先利其器，在介绍写好文档的方法前，先分享一些写作工具。

多年以前，写文档基本都是用 Word，但 Word 其实是有很多的问题和不足的。比如要自己手动调整格式、同一份 Word 文档由于兼容性问题在另一个电脑上打不开或者排版错乱等等。

所以现在我强烈推荐大家学习 Markdown（一种轻量级标记语言），可以让你用同一套语法轻松编写出排版、格式一致的代码。

比如用 “## 二级标题” 来表示二级标题，用 “> 引用” 来表示引用文案等。

现在很多编辑器软件都支持 Markdown，比如我们平时用的 VS Code、JetBrains 全家桶。但如果要选择一个体验最好的本地 Markdown 编辑器，我推荐大家使用 Typora，这也是自己用了多年的软件。

在写文档的过程中，也经常需要一些绘图来辅助理解，比如流程图、架构图等等，可以使用在线工具 Draw.io、经典软件 Visio 等。如果需要绘制思维导图，可以使用 XMind。如果要生成一些配图，可以使用目前很火的 Midjourney（或者我们的鱼聪明 AI）。

如果你需要把文档发到其他自媒体平台，可以直接把 Markdown 内容复制粘贴到 mdnice 网站中，它会自动帮你生成精美排版的文章。

此外，随着 web 前端技术的发展，线上文档写作网站也越来越强大，如果要团队协作、实时共享文档的话，可以选用语雀知识库、腾讯文档、飞书文档等工具。

方法

“抄”

首先，想写好文档，要做的第一件事是 “抄”。

哦不，读书人的事，应该叫 “学习借鉴”。

如果你不会写文档，比如项目文档、设计文档、用户手册，怎么办？

很简单，到网上找优秀的成品，去模仿。

不单单是写文档，做自媒体、做产品、写论文、学手艺，你想做好任何事情，第一件事都应该是：看看别人怎么做的，向别人学习。

• 你要开发网站，就去网上找现成的网站
• 你要做视频，就去网上找爆款视频

这是最简单的道理，很多东西都有前人做过，所以哪怕别人不分享教程，只要你去模仿，用点心也能完成。

再加上现在开源文化盛行，很多项目和文档都在 GitHub 等平台公开可见。当你要写一个文档时，直接先复制一下知名项目的 README.md 文件，然后把原本的目录大纲保留，把内容换成自己的，就得到了一份很标准的文档，就这么简单。

等你阅读和编写的文档多了，自然也能形成一套属于自己（团队）的写文档方法。

写作流程化

很多人讨厌写文档，就是因为感觉没有思路、无从下笔、完全不知道写什么。

我以前也常常是新建一个空白文档，然后对着它发呆。。。

但后来随着写作次数越来越多，我也修得了一套能够快速写出内容的方法，我把它称为 “写作流程化”。

什么叫流程？你去食堂买早饭，先排队、再买包子、再打豆浆、再找座位，这就是一个刻在 DNA 里的流程。

如果你也能有一套明确的写作流程，那么写作就像你买早饭一样简单。

具体怎么做呢？

1）先想清楚文章的结构，根据主题写出大纲

比如我在写这篇文章时，先写了 “什么是文档？为什么写文档？怎么写出好文档？怎么管理好文档？” 这几个小标题，把整篇文章的框架定下来。而不是从上到下漫无目的地去写，想到哪儿写到哪儿。

写大纲的过程本身就是在培养你的结构化思维 —— 把复杂的问题进行结构化拆解。如果你发现自己写大纲都很困难，那么不妨尝试把时间线作为大纲，按照由远及近的顺序，依次去写你各个时期的想法。

2）填空

只要确定了大纲，你就可以有 100% 的信息，这篇文章你必然能写完。因为剩下要做的就是往每个章节下填空就好了。

类似于有个导师给你规划好了你要做哪些事，你就有了个目标，更容易坚定地执行下去。

3）优化

写完大致的内容后，我们要整体读 2 - 3 遍文档，进行适当地优化。

就像我们写代码一样，虽然功能是完成了，但是代码可能写得比较烂，提交代码前得再改改。

列举一些常见的优化点：

1. 修改错别字
2. 小标题间增加关联语，承上启下，使内容更连贯
3. 重点前置，把文档的关键信息放到开头，吸引人阅读
4. 图文并茂、多用比喻，让文档更易于理解

这一套流程走下来，一篇完善的文档就诞生了。

持续优化

无论是自己写学习笔记、还是项目文档、用户手册，都不是写完一版就结束了的。好的文档是需要持续优化迭代的，如果有人指出了问题或者文档内容有过期，应当即时修复处理。不然错误的文档不仅不能帮助到人，还会产生误导。

像我们在开发鱼聪明 AI 的过程中，就很不幸地参考了一篇胡说八道的过期文档，让本就不富裕的团队雪上加霜。

积累

经常有朋友问我：鱼皮你平时又上班又高产胜母猪，怎么做到的？

其实我有一个习惯，就是会把生活中觉得有趣的事、或者突然想到的灵感记录下来，每隔一段时间去整理一下，后来我惊喜地发现，有些碎片化的内容竟然可以串起来讲，组成一篇文章。

就像打游戏一样，你想刷的装备一直出不来，你不在乎的装备碎片反而攒了一大堆。结果有天，你发现碎片都能够合成完整的装备了，竟然还挺好用，这就是无心插柳柳成荫吧。

写文档也是，哪怕你无法写一篇全面系统的文档，在你工作中遇到 Bug 的时候，随手开个文档记录下来；再遇到 Bug 的时候，就再打开之前的文档记录下来。次数多了，稍加整理，一篇高质量的文档不就来了？

举例

以我们的鱼聪明 AI 来举例，刚开始写项目立项文档时，按照上述的 “流程化” 方法，先定了文档大纲：

1. 为什么做？项目背景
2. 做什么？需求分析
3. 怎么做？设计方案
4. 具体怎么做？工作安排等等

然后才是一条一条地去补充完善，之后在每次开会和上线后，再持续更新完善一下这个文档。

完善文档的过程中，我也会看到很多之前记录的内容，提醒着自己在做这个项目的过程中不要走偏。

怎么管理好文档？

随着我们项目的不断迭代，文档数也越来越多、越来越零碎，怎么管理好这些文档，让大家需要阅读时能快速找到，这是个大问题。

尤其是对于大项目来说，假如 100 个人一起开发，每人写 10 篇文档就是 1000 篇文档，怎么对这 1000 篇文档进行管理呢？

要先有一个意识：尽早发现问题，会比后期解决问题的成本要低很多。

所以管理好文档这件事，应该主要靠 “前期的策略” 和 “中期的持续优化”，而不是后面再去人工整理大量的文档。

代码屎山就是这么来的，烂代码堆得越多，越没人敢动。

所以首先，我们在开始项目前，就要建立好一套规范的文档体系。

1）文档线上化

只要是和项目 / 工作相关的文档，不要让大家在本地去写，而是直接用线上文档去实时协同。很简单的道理，你本地改了一段话，别人本地也改了相同文档的一句话，那最终以谁的为准？

像我们 鱼聪明 AI 的所有内部文档，都是使用语雀知识库来托管的，所有项目的信息在团队内部公开透明，从而尽最大地可能性消除信息差。

而且线上知识库还有一个好处，就是查找搜索方便，整个知识库的内容一键随便搜。

2）分组

随着文档或知识库越来越多，必然就会给大家的查找造成负担。所以我在最开始就给所有团队内部的知识库都按主题做了分组，如下图：

每个知识库下的文档，也建立了相应的分组：

当然，分组这个操作也是需要持续做的。如果刚开始没有办法预估会有哪些分组，那就等后面需要分组的时候，即时新建就好。

3）访问控制

所谓访问控制，就是让部分成员只能看到部分文档。这么做不仅是为了安全，也可以让大家尽量聚焦在自己的工作上，更能找到自己需要的文档。

目前我们鱼聪明 AI 团队的每个知识库都是有严格的访问控制的，只有大家需要看某个知识库时，我才会给他们开对应的权限。当然这也不是说要限制团队成员的学习，如果他对某个知识库感兴趣，可以直接申请查看。

主流的线上文档软件基本都支持访问控制和权限管理，实现上没有什么难度。

4）培养团队文档文化

还记得这篇文章开头我给大家讲的自己的故事么？有些人可能是没有写文档的意识、或者就是不爱写文档的！如果这个人又是项目的重要贡献者，那么他个人掌握的、团队不清楚的信息就会越来越多，最终就会出现 “他的代码别人动不了”、“他一走项目就完蛋” 的情况。

为了把这种风险扼杀在摇篮里，我反复跟团队的成员强调，一定要多写工作文档、即时同步信息，甚至对于一些重要的工作，我会把文档作为大家工作成果的一部分。慢慢地，大家就养成了写文档、文档分类的习惯。