说说程序员写文档这事

缘由

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

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


不愿意写文档的原因

不愿意写文档,有几方面原因:

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

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

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

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

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


写文档的益处

不过,写文档是有多方面好处的:

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

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

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

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

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

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


值得写的文档

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

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

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

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

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

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

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

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

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


如何写好文档

如何写有益的文档?

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

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

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

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

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

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


文档写作能力

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

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

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


posted @ 2021-08-14 05:18  琴水玉  阅读(74)  评论(0编辑  收藏  举报