和工业聚一起聊聊技术与写作

今天我们来一起探讨一个有趣的话题，技术与写作。

整体内容分成八个部分。前三个部分，我们先回答几个纲领性问题：技术与写作的关系是什么？技术写作的构成有哪些？以及，为什么要参与技术写作？

第四到第七部分，我们分别阐述技术写作的定位、质量分析原则、写作误区和基本模式。

第八部分进行回顾与总结。

一、技术与写作的关系

可能在部分开发者心里，写作是一项从大学毕业后就离自己很远的活动。

我不知道他们有没有注意到，写代码，跟我们理解的传统意义上的写作，似乎还挺像。

比如，都有很多不同的语言，可以表达相同的事物或者逻辑。

代码里有不同的编程语言，比如 JavaScript, TypeScript, Java, Python, PHP 等等。

我们日常使用的自然语言，也有很多种类，比如汉语、英语、日语、韩语等等。

编程和写作，都是按照一些语法规则，摆弄一些词汇和符号。

我们观察到，编程语言和自然语言背后，好像具备某种共性。

那么，这是一种偶然吗？这只是我们牵强附会的联想吗？

当我们回顾计算机科学的历史，在一群早期的奠基人和祖师爷当中，我们发现了语言学家的身影。

比如左侧图片里的那位长者——乔姆斯基。虽然图像里他的背景是 jQuery 代码，衬托得他像一位计算机科学家，但严格来说，他是一位语言学家。

在 1956 年，他提出了乔姆斯基层级结构，把语法根据生成规则分成了 4 个等级。

了解编译器，或者经常写 Parser 的开发者，可能很熟悉。比如属于 Type-3 的正则语言，属于 Type-2 的 Context-Free 上下文无关语言，属于 Type-1 的 Context-Sensitive 上下文相关的语言等等。

有一个经典技术问题是，为什么不能用一般的正则表达式去匹配 HTML 结构？

在 1956 年就能回答这个问题，因为 HTML 的语法属于 Type-2 等级，而一般的正则语言是 Type-3，只靠它自己，很难解析包含递归/嵌套的语法结构。

虽然乔姆斯基层级结构，对编程语言理论、编译器、形式语言等理论计算机科学的研究，有深远的影响。但它最初那篇论文里，是用英语这种自然语言的语法作为分析案例。

因此，乔姆斯基层级结构，可以看作编程语言和自然语言，在现代语言学里的交汇。

不管是编程语言，还是自然语言，从语言学的角度，它们就是两类用途不一样但遵循着相同语法层级结构的语言分类。

在这个背景下，我们可以尝试，定义广义写作——

使用基于特定文法规则的符号系统表达特定结构和涵义

在这个概念下，我们可以更清晰地看到，编程技术和写作的关系。

编程，是面向机器的写作，主要使用编程语言，主要是确定性的表达。

而平常意义上的写作，是面向人类的写作，主要使用自然语言，主要是概率性的表达（概率性的表达在这里是指，更加模糊的，更加容易误解的表达）。

编程本质上是写作的一种形式，写代码是一种写作活动。

这是我们回答的第一个纲领性问题——技术和写作的关系。

那么，第二个纲领性问题是，技术写作又是什么？

二、技术写作的构成

技术写作属于前面说，面向人类的写作，但它又跟技术息息相关，它围绕技术主题，向其他开发者表达技术内容。我们可以尝试给出它的定义：

技术写作是围绕技术展开的的文本创作活动

可能在很多开发者眼里，技术写作，一般就是指写技术文章，是一种业余时间的爱好，是可有可无的。跟我们日常写代码工作，不直接相干。

这是一种比较片面的理解。

事实上，技术写作在程序员日常工作中的占比，比我们想象的高很多。

并不是只有技术文章这一种形式的技术写作。

• 代码注释(Code Comments)

• 技术文档(API Documentations)

• 需求文档(Requirements Documents)

• 工作邮件(Email)

• 错误报告(Bug Reports)

• 即时聊天(IM Messages)

• 技术文章(Technical Blogs)

• 其它类型……

这一系列围绕技术的文本创作活动，都是技术写作的一部分。甚至，你参加晋升答辩时，写的 PPT 也属于技术写作。

写技术文章，是其中一小部分。当然，也是很重要的一部分。相比碎片化的其他形式，技术文章更加可以凝聚和系统地阐述技术观点，可以帮助我们梳理很多技术问题。

当我们放开视野，我们会发现，技术写作无处不在。

为了表达上的方便，后面我们说技术写作的时候，如果没有特殊声明，它就是指写技术文章。因为对技术文章的要求，往往也适用于其他类型的技术写作。

那么，我们来看最后一个纲领性问题——为什么要参与技术写作？

三、为什么要参与技术写作

这听起来像是一个很傻的问题，因为前面我们已经把技术写作定义为程序员日常工作的重要组成部分，这已经足以推导出我们需要参与技术写作，它是我们工作要求的一部分。

不过，对这个问题，我们依然可以提供不同视角，提供更多的信息，在一个更广阔的认知图景里，看到技术写作的位置和价值。

我总结了一个能力层次模型。

第一层是知识储备，我们从学校里学的那些抽象的理论知识，什么数学、物理、微积分、计算机基础等等，就是我们知识储备的一部分。

我们很多时候，其实并没有那么理解这些知识，它们从何而来，它们解决什么问题，它们有什么用？我们对此感到模糊。

往往，只在考试做题的时候，能运用一下这些知识。这就到了第二层——理解水平。

知识储备，不等于理解水平。我们常常发现，同一个知识点，在学霸那里生龙活虎、融会贯通，在我们这里却呆若木鸡。

我们常常很久之后，才意识到之前在学校里学的某些知识的真正用途。

我们可能需要，努力提升对知识的理解水平，更好地优化我们第三层——实践能力。

理解水平，不等于实践能力。一个计算机毕业的博士，并不会因为他在计算机领域的知识储备和理解水平，自动成为写代码的高手，自动成为成熟的软件工程师。

理论知识，往往是在排除了很多现实干扰因素，在一个相对干净和理想的假设下，建立起来的。

到了实践环节，理论知识里省略的部分，全都冒出来了。所以，实践能力需要额外训练和积累。特别是在技术实践中，我们需要处理大量的细节、旁支，需要跟其他同事沟通、协作。很多事物，理解起来简单，但做起来却很难。

所谓的实践能力，就是在资源有限且干扰因素众多的情况下，不断克服一系列现实问题，去达成目标的能力。

我们关注的技术写作，则属于第四层——文本表达。

在技术领域，实践能力不等于文本表达能力。能写出一手好代码，并不意味着也能写出一手好文章。反过来也成立，能写出一手好文章，也不意味着能写一手好代码。

所有我们才区分技术实践能力和文本表达能力，把它们看作两个维度。

最后，在第五层的是口语表达。这个应该很容易理解，大部分作家，并不擅长演讲。

口语表达受到生理限制、口音、心理素质乃至社会地位高低等更多因素的影响。需要努力去一一训练和克服。

那么，这五个维度的能力，互相之间有怎样的影响关系？

我们可以从一个经典问题入手——如何编写优雅的代码？

表面上看，这是一个技术实践问题。很多开发者也确实想通过掌握很多代码技巧，写出优雅的代码。

他们慢慢地发现，自己掌握的代码技巧，好像只在简单的问题上奏效。复杂一点点，又破功了，又写成面条代码了。

他们觉得，这是一定是我掌握的代码技巧还不够多。

仔细一想，我们可能发现，优雅的代码固然是一个实践问题，也是一个认知问题。优雅的代码，不只是靠技巧得到的，更主要的是，靠对问题充分的、清晰的认识，然后用代码表达出来。

也就是说，第三层的实践能力，依赖上面两层的能力。

当我们在知识储备和理解水平的维度，对问题有了充分的把握，在做代码实践时，我们能写出更优雅的代码。

同理，第四层的文本表达，也依赖前面三层。

很多开发者写文章时，也不知道从哪里开始写，也不知道哪些该写，哪些不该写。他们误以为，这是写作技巧不过关，需要学习各种写作的技巧，特别是技术写作的技巧。

这可能也是一种误解。尽管写作技巧是需要训练的，但写不出好的技术文章，不仅仅跟技巧有关，跟我们的代码实践能力、理解水平和知识储备，也息息相关。

我们不知道从何下笔，也可能是因为我们确实没有把问题想清楚，代码写得也不咋地。

这也是为什么说，当我们有技术沉淀时，我们写出的技术文章会更好。所谓的技术沉淀，就是在前三层的积累。

第五层，口语表达也是一样。当我们觉得我们很难跟领导或者同事们，表达清楚我们的技术观点。我们应该想到，这也未必是演讲技巧的问题，可能我们用文字写出来，也是不清晰的。

总的来说，当我们的知识储备到位时，我们的理解会变得更清晰；当我们的理解水平到位时，我们的代码会变得更清晰和优雅；当我们的代码实践水平到位时，我们的技术文章，会写得更清晰；当我们文本表达能力到位时，我们的口语表达会变得更清晰。

反之，一切都会感觉很混沌。

训练这五个维度的能力的方法，我写在了右边的框框里。就是多加学习、多加思考、多加实践、多加写作、多加表达。千万不要觉得自己内向，或者文笔不好，就只是埋头写代码，这样会有很大的局限性。

前面已经说过了，技术写作无处不在。你的晋升 PPT、你的简历也是文本表达的一种，你晋升述职，又是口语表达的一种。

一些开发者，代码实践能力不错，也做了很多有价值的工作，但在文本和口语方面，缺少自我训练，不能在关键时刻有效地向其他人描述他的工作价值。

在文本和口语表达维度上的短板，成为了他们的硬伤，这是很可惜的。

想要把知识融会贯通，需要在这 5 个维度全面发力。从现在开始，从技术写作开始，去贯通技术实践和技术表达。

这就是为什么我们要参与技术写作。

四、技术写作的几种定位

当我们决定要积极参与技术写作时，我们需要做的第一件事，就是找准自己的定位。

不同发展阶段的开发者，可能有不同的倾向。比如技术专家型、技术自媒体型、技术作家型等等。

不同定位的技术写作，要做的事情不完全一样。比如

• 积累丰富的一线技术经验

• 积极与同行交流技术问题

• 深入研究特定的专业方向

• 努力理解和捕捉大众偏好

• 及时把握当下的技术热点

• ……

这些事情，彼此之间可能是互斥的。当我们把精力放在一线技术研发，或者特定技术方向深入研究，我们可能对大众偏好没那么关心，对当下的技术热点没那么关注，也没那么多时间跟进。

我总结了一个“不可能三角”——高产量、高质量和可持续，这三个维度，很难同时成立，最多包含其中 2 个。

高质量+高产量，一般就是有深厚沉淀的技术专家，出来写技术连载了，走科普向。但这个很难持续，高强度的内容输出，总有掏空的一天。

高质量且可持续，一般就是技术专家偶尔出来写几篇技术文章，把自己最近的工作进展，跟大家汇报一下。这是研究向，产量不高。

高产量且可持续，一般就是经常关注技术热点的自媒体，为大家整理入门材料、技术八卦等等。偶尔可能会有一篇两篇质量不错的文章，但平均质量，不如科普向和研究向的。

能做到高质量且高产量且可持续的，可能是超人。我们大部分都不是超人，所以不讨论了。

值得一说的是，在不同时期，我们可以选择不同的定位，它们是可互相转换的。

我们需要做的是，选择当下我们觉得自己能做到的、适合我的定位。

五、文本的质量光谱

在技术领域，有一句名言：

If you can’t measure it, you can’t improve it.

如果我们不知道怎么衡量，那么我们很难做优化。

这是做代码的性能优化的首要原则，我们必须先建立衡量性能的基准，用数据说话。不能拍脑袋重构代码，觉得理论上性能应该有所提升。实际上呢，缺乏证据，而且代码优化有个墨菲定律，优化后的代码，比优化前的性能更差。

放到技术写作里也成立。如果我们不知道如何更客观地评估文本的质量，我们怎么知道我们的技术写作能力提升了？

所以，我尝试总结了一个评估文本内容质量的光谱。

最中间的，信息/事实是中性的。越左边，主观和感性成分越浓；越右边，客观和理性成分越高。

对比“观点/意见”和“知识/经验”这两个，当我们一个认知，缺乏事实基础的时候，它属于我们的个人观点，偏向主观，在事实的左边。当我们的一个认知，有自己亲身经历作为事实支撑时，偏向客观，在事实的右边，它是我们的个人经验。

观点的左侧“感受/体验”，就是更加主观，还没凝聚成明确的表达的状态，就是我们感受到了事物，我们体验到了事物，但我们还没有做出评价，我们既没有意见和观点，也没有正面或者负面的态度，我们只是感受一下。

感受之后，我们后续可能产生积极的、或者消极的情绪跟态度，它们是更加主观的体验，表现为，我喜欢什么，我不喜欢什么，我讨厌什么，我期待什么。我们不需要解释为什么，或者我们也解释不清楚，反正我们就是有一种情绪和态度。

当我们尝试解释自己的感受时，就会往右侧转移，先是形成自己的观点/意见，然后找到事实基础，慢慢摸索出知识和经验。

只靠一个人的摸索，可能会有统计偏差。当我们想要更进一步，获得更加可靠的知识的时候，我们需要动用一些科学手段，去减小误差，我们会建立理论和模型，做实验去验证，逐步排除错误的模型，找到更加正确的模型。

在这个科学探索的过程中，有时候我们会开辟新的领域，或者用更加完备的新理论，替代旧理论。就像相对论和量子力学提供了比经典物理学更完善的对世界的解释一样。

这种开辟新领域或者发现新范式，可能几十年，上百年，甚至几百年才遭遇一两次。可遇而不可求，我们将它放到文本质量维度的最高位置。

总的来说，越靠近右侧，越接近科学研究的要求。通常我们写技术文章，是从中间的事实层次出发，往左右两侧覆盖一两个层次，并且尽量让我们的内容偏向右边。

那么，根据这个光谱，我们如何衡量一篇技术文章的质量呢？

首先，我们要做的是，辨析观点和事实。这是一项需要训练的能力，我发现很多开发者都不具备这种能力，一篇文章，只要用 1 分事实，裹上 9 分谬论，就能把他们迷得团团转。骂都骂不醒，你说他们，他们还会反问：可是他说的也不完全没有道理呀，然后把那 1 分的事实重复一遍。他们没有明确区分一篇文章里，哪些是观点部分，哪些是事实部分，事实部分是否支撑了观点部分。

如果一篇文章，事实部分含量很少，通篇是个人观点，甚至充满了我喜欢什么我不喜欢什么，什么什么是错误，什么什么又是垃圾等情绪和态度。我们说，这种文章，态度大于内容，是不好的。

如果一篇文章，总是挑一些极端的案例，放大它们，渲染它们，明显忽视存在其他反例。这种属于幸存者偏差，也是不好的。

好的文章，会平衡内容的分布，增加客观部分，减少主观部分。多使用现成知识、理论或者研究成果，少自己发明，要站在巨人的肩膀上。

如果一篇文章，全是引用现成的结论，像抄书一样，确实也没有趣味。还是要有一些自己的态度和观点，但要控制比例，不能太多，前进一小步就足够了。

总的而言，高质量的文本，是在事实和理性的基础上，建构更加可靠的知识体系。

六、技术写作的误区

我们再来聊一下技术写作的误区，从我个人有限观察来看，有 3 大类误区，值得关注。

我先解释一下“警惕”的意思，“警惕”不是指不能做，而是说不要觉得做了就一定加分，把文章写得花里胡哨，形式大过内容，还觉得很骄傲。

“警惕文艺向”，这个类别很有趣。把技术文章写得很文艺，其实可以得到很多好评。文章底下的评论往往是一片赞叹，比如说什么好文采呀、什么文笔老辣呀……

作者因此也容易飘飘然，觉得这个方向很成功，下一篇更加文艺范儿。

如果只从读者反响来判断技术文章的好坏，很容易被这样迷惑。

其实读者那种赞叹，往往非常廉价，也不走心，主要就是捧个场。只要有作者愿意凹文艺造型，就有一批读者愿意捧臭脚。

我看过的大部分凹文艺造型的技术文章，把技术部分和文艺部分，分别考察，两个部分都很平庸。

从技术的专业角度考察，文章里很多知识没说到点儿上，也没有按照有效的结构去展开。

从文学审美的专业角度考察，大部分也就中下游水平。只是用在技术文章里，读者对文学性的要求很低，所以才觉得不错。真让他们写严肃一点的文艺内容，换一种考察标准，大家可能就不买账了。

而且那些排比句、文言文以及伤春悲秋的情绪渲染，在技术文章里，没有信息量，都被当成套话，看两句就跳过了。没人会认真咀嚼和感受里面的文字趣味，那里也没什么文字趣味。

除了抒情流，还有一种境界流，常见于脱离一线技术很久的老板们。他们常年不写代码，跟前沿技术也脱节了，技术感知力退化了。他们写的文字，就会包含很多浮在空中的什么战略思考，比如引用他们最近看的一些管理学书籍里的概念，引用刘慈欣《三体》的黑暗森林，引用凯利·凯文的《失控》，王阳明的心学，或者庄子、老子、墨子和孔子什么的名言。

总而言之，境界流的文字，就是让读者感觉作者思考层次很高。

但是，缺乏技术细节的文章，很难称得上是一篇优秀的技术文章。

可能它们是优秀的散文、小说、故事会，或者管理学文章，或者人生感悟，但它们不属于严格意义上的技术文章。所以，千万不要在还没有成为不写代码的领导之前，就模仿领导的风范，写境界流的文章，满口抓手、闭环、组合拳跟底层逻辑。

第二种是民科向，又分成两种类型，第一种是学而不思型，这类作者生怕大家不知道他们博学多才，在技术文章里杂糅多个不同学科的概念和术语，他们最喜欢的可能是物理学和心理学，比如物理学的熵，心理学的弗洛伊德……

学而不思型的技术文章，跟前面文艺向的问题有点相似。这类文章下面，也常常是一篇赞叹，比如称赞作者博学、内容高深，然而，如果把他们文章里涉及的学科部分，全部分开来看，每一个做专业考察，很容易发现，作者不懂那些知识，主要是在滥用。

对应了网上的一个段子“一个博学多才的网红，平时看着觉得学到挺多的，直到他开始说到我们的专业领域”。

另一种则是思而不学型。这类作者，学习的知识不多，但他们很会抓住几个关键词，发挥自己的联想，在自己的定义里越走越远。而且，其他人很难跟他们有效对话，因为大家虽然用的是同一个词，但他们不跟随主流的定义，结果就是鸡同鸭讲，不欢而散。

思而不学型的技术文章，对技术的初学者很有迷惑性。初学者分辨不了，作者说的究竟哪一部分是他自创的，哪一个是部分在陈述主流知识。

对于初学者来说，不去看那类技术文章是最佳选择，初学者优先去看主流的、权威的学习材料。有了一定积累，培养了一定的分辨能力后，再去看社区的技术文章，会更好一点。

第三类是娱乐向。一种是去文本化，一篇文章里，能用表情包、动图或者短视频的时候，绝不用文字。

另一种是去严肃化，写着写着，就开始插科打诨，跳到八卦、闲聊、题外话，总之就是不专注于围绕技术重点做推进。

作者不严肃地写，读者们也不严肃地看，在一片轻松祥和的氛围里，大家果然又没学到什么呢。

这其实没有什么不好。只是从技术写作的角度，这未必是我们追求的。

如果我们想要的是严肃型的技术写作，我们需要打从心底去相信，相信形式大于内容，相信认真的态度、扎实的文本、诚恳的表述，自有万钧之力。

七、严肃型技术写作的基本模式

那么，问题来了，严肃型技术写作究竟该怎么做？

其实就是，参考论文的基本内容结构，按照相似的方式展开我们的技术观点。

论文的模式支撑了近几百年的科学发展，是严肃型文本的绝佳模仿案例。

大家看这里，是不是回忆起在大学时期写毕业论文的恐惧？

其实不用紧张，技术文章也不必像论文那样严格，我们只是粗略地模仿，不是真的要写论文。

一篇技术文章大致的脉络可以是，先写摘要或前言，概括一下这篇文章要写什么。

然后是介绍一些基本背景和知识，引导出我们关心的核心问题。

然后是写结构概览，描述一下我们内容主体分成多少部分，多少环节，分别解决什么问题。

然后是有层次地呈现文章的主体内容，最后做一个总结或者反思，当然，也可以加一些未来展望什么的。

文末可以添加致谢以及参考文献。至此，我们得到一篇结构完整的技术文章。

通过模仿论文的结构，我们不必花太多心思在文章的形式上，去搞什么创意。我们可以专注于提升文章的内容质量。并且，由于我们每一篇文章的结构，都大致相同，熟悉我们的读者在阅读的时候，更加轻松，他们已经对后续内容是什么有正确的预期，减少 Surprise。

八、回顾与总结

那么，我们来回顾一下，今天的内容：

我们知道了，编程本质上是一种写作活动；我们知道了技术写作也是程序员日常工作的重要组成部分；我们知道了参与技术写作有助于贯通实践和表达；我们知道，技术写作需要找到符合自己当前发展阶段的定位；我们知道如何评估技术文章的质量，知道需要让我们的内容，往更加理性、客观的方向努力；我们需要相信和坚持内容大于形式，避免一些技术写作的误区。

最后，经久不衰的论文结构，是严肃型技术写作的最佳模仿对象。

以上。