说说程序员写文档这事

缘由

在知乎看到一个提问：“为什么程序员讨厌写文档？” ，分享下自己的一点思考。

并不是讨厌，只是不喜欢，通常是因为懒；但如果还要被迫写自己不认可价值的文档，那就从“不喜欢”转变成“讨厌”了。

不愿意写文档的原因

不愿意写文档，有几方面原因：

• 语文水平不好，一写就暴露了。写几句话都难，何况写一篇文章？但我强烈建议多写写就好。试想：如果缺乏清晰的表达能力，如何有条理说清楚工作成果，如何给自己争取升职加薪的机会呢？

• 团队氛围不提倡。别人不写文档，那自己就得抱着“我不入地狱谁入地狱”的心态，甚至还不讨好。本来是希望能帮助新手更好熟悉帮团队更好维护业务，有的TL可能会默认你的“英雄行径”，既不拥抱也不反对，有的可能还嫌“效率低，KPI做得不够好”。这种情形下，建议适量写，不要因为外在因素影响内在驱动，但也不要花费太多时间去对抗。

• 思维没转变过来。总觉得代码是第一生产力。实际上，文档和代码都是表达，都是解决途径之一。能动嘴皮子解决的就不用代码解决，能用一行代码解决的就不动嘴皮子。千万不要以为对产品或提要求的人百依百顺就是真爱，别人就喜欢了。你做与不做，别人都有一样的烦恼，真爱是在博弈中产生的。不是所有代码都值得去写的。从某种意义来说，代码只是针对不同领域（今天是交易，明天是教育）写相似的 for-if 语句，代码技能并未有飞跃性提升，不若多拓展一些解决问题的途径，减少写不必写的代码。有时，说服力比写代码更厉害。

• 不够重视表达。程序开发，是集逻辑、设计与表达为一体的。表达是其中重要一部分。遗憾的是，很多国内程序员还不够重视表达部分。我想强调的是：表达沟通与写代码的技术技能同等重要！

• 惰性。优秀的程序员是懒惰的，尽可能避免低效的事情。因此，程序员大多不喜欢公文式的文档。但我想说：优秀的程序员也是反惰性的：当他意识到一件事的重要价值时，就会克制做这件事。写文档这事是反惰性的，然而人的原生特性是懒惰却非反惰性的。你看看 JDK 那些大牛的类注释写得多详细多工整！相比而言，一些程序员代码水平不怎样注释也不好好写。差距多大！

写文档的益处

不过，写文档是有多方面好处的：

• 正如一位答友所说：文档是极好的沉淀思路的方式。善于写清晰的文档也会有助于写清晰的代码。日积月累，你的思路会越来越清晰，内心亮堂。这不仅仅对于开发有益处。

• 帮忙团队更好地熟悉和维护业务，建立团队规约；尤其适合新入职同学更快地熟悉团队工作氛围和业务相关，更好地上手。

• 建立在团队和内网的好印象和影响力，与公司内的更多优秀工程师建立良好的技术交流渠道。

• 良好的技术博客能让你在候选者之间更容易脱颖而出。一个创作优美又有一定深度和广度的技术博客摆在面试官面前，是他难以抗拒的诱惑。

• 我现有公司CTO鼓励写文档。高级别管理者必须具备良好的文档编写能力。但不是那种公文式的文档，而是知识类工作紧密相关的文档。当大多数人都鼓励写下自己的工作所得和总结时，公司的文档空间就变成了一座知识宝库。你能从中获得很多的姿势。我有幸见证了这一点。

文档不是降低开发效率的祸首，反而是一种有力的帮手。当然，写文档也有讲究：有哪些值得写的文档？怎么才能写一篇好的文档呢？

值得写的文档

有哪些有益的文档值得去写？

• 技术沉淀。推荐认真写。比如在项目中接触了新的技术，有必要仔细研究下，写篇博客分享下；或者有一些心得，及时写下来。

• 问题排查。有多少次，你遇到相似问题或别人问你一个问题，你似曾相识却又忘了当时是怎么解决的？问题既多又琐碎，及时记录，避免后续又要花相同的精力去解决。

• 设计方案文档。强烈推荐认真写。设计方案文档是对系统整体的理解、设计与实现的书面表达，是综合考验一个人设计能力、技术能力、表达能力的场景，可以帮助你梳理好思路，也可以向别人表达你的想法，收获有益的反馈，从而考虑更周全，避免有些地方因为不了解存在缺陷导致后期大量改动。此外，它也可以在项目中起共识和开发指导的作用（比如你是主程、技术负责人或架构师）。它实在是你提升技术能力、架构设计能力和沟通表达能力的有力帮手。

• 业务文档。推荐适量写。有助于团队的人快速熟悉，减少踩坑，是协作共赢的事情，但要求每个人都必须有所投入，且不计较多寡。

• 项目文档。有助于项目成员更好地理解项目背景、目标、里程碑、技术方案、风险控制，做到整体把控。如果你想成为优秀的 PM，或者具备良好的项目管理能力，需要重视项目文档。

• 需求变更文档。严格来说，这不是开发人员要写的，但是可以记录每一次需求变更的原因，年底一并清算。

• 新人指南。一个优秀的公司或团队一定是非常注重新人培养的。帮助新人更好融入团队，不仅仅是对新人有益，也是对自己有益。力所能及帮助新人，同时温故而知新。人不仅仅只是为 KPI 而活的。多一些人情味。

• 代码注释辅助。代码里有些地方用少量注释说不清楚的，可以写一篇文档，然后附到代码里。

如何写好文档

如何写有益的文档？

• 列提纲。先把提纲列好，针对提纲中的每个标题写两三句直接想到的话，然后再扩充成一段话或两段话（通常可以加些背景或引用名言）。

• 关键字导航。先提炼出关键字，再围绕关键字来丰富内容。

• 简洁明了。只写相关的内容，少写无关的。少量打趣是可以的。

• 通用模板。可以套用一些好的文档模板，填内容即可。比如：设计方案的模板：背景-目标-名词解释-总体思路-系统模块图-详细设计-技术规格-开发计划-测试建议-部署事项-其它问题（比如历史遗留、兼容性等）。

• 12345。对于技术文档而言，一种最简单最常见的写法就是罗列一二三四五，分别阐述清楚即可。不必写得像散文那样，形散神不散。真的，有点难的。

• 清楚明白。把事情说清楚明白就可以了，不必有意渲染，或者想达成什么夸张的效果。

文档写作能力

文档写作能力与编程能力，都是程序员要具备的通用技能。而且，文档写作的受众面和影响力更大，因为它可以面向所有的用户，无论是否懂技术或某一门编程语言。

如果你只会某种编程语言或者某种技术，又缺乏好的文档写作能力，那将会非常受限：难以有效地向普通人群分享你的想法，甚至也难以向更多的同行分享你的想法，只能局限在一个狭窄的技术领域内。

祝愿你早日有一种呼风唤雨的文档写作能力。