作者简介

工业聚，携程高级前端开发专家，react-lite, react-imvc, farrow 等开源项目作者，多年文本创作经验。

今天我们来一起探讨一个有趣的话题，技术与写作。技术与写作的关系是什么，技术写作的构成有哪些，以及对开发者来说，为什么要参与技术写作？如果要进行技术写作，技术写作都有哪些定位，如何分析一篇技术文章的优劣，是否有一个技术写作的基本模式可以参考，都将在下文一一道来。

一、技术与写作的关系

可能在部分开发者心里，写作是一项从大学毕业后就离自己很远的活动。不知道他们有没有注意到，写代码，跟我们理解的传统意义上的写作，似乎还挺像。

比如，都有很多不同的语言，可以表达相同的事物或者逻辑。代码里有不同的编程语言，比如 JavaScript, TypeScript, Java, Python, PHP 等等。我们日常使用的自然语言，也有很多种类，比如汉语、英语、日语、韩语等等。

编程和写作，都是按照一些语法规则，摆弄一些词汇和符号。编程语言和自然语言背后，好像具备某种共性。这是一种偶然吗？只是我们牵强附会的联想吗？

当我们回顾计算机科学的历史，在一群早期的奠基人和祖师爷当中，发现了语言学家的身影——乔姆斯基。在 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.

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

放到技术写作里也成立。如果我们不知道如何更客观地评估文本的质量，我们怎么知道我们的技术写作能力提升了？所以，我尝试总结了一个评估文本内容质量的光谱。

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

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

观点的左侧“感受/体验”，就是更加主观，还没凝聚成明确的表达的状态，就是我们感受到了事物，体验到了事物，但还没有做出评价，我们既没有意见和观点，也没有正面或者负面的态度，我们只是感受一下。感受之后，后续可能产生积极的或者消极的情绪跟态度，它们是更加主观的体验，表现为我喜欢什么，我不喜欢什么，我讨厌什么，我期待什么。我们不需要解释为什么，或者我们也解释不清楚，反正我们就是有一种情绪和态度。

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

只靠一个人的摸索，可能会有统计偏差。当我们想要更进一步，获得更加可靠的知识的时候，我们需要动用一些科学手段，去减小误差，我们会建立理论和模型，做实验去验证，逐步排除错误的模型，找到更加正确的模型。在这个科学探索的过程中，有时候我们会开辟新的领域，或者用更加完备的新理论，替代旧理论。就像相对论和量子力学提供了比经典物理学更完善的对世界的解释一样。这种开辟新领域或者发现新范式，可能几十年，上百年，甚至几百年才遭遇一两次。可遇而不可求，我们将它放到文本质量维度的最高位置。

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

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

首先，我们要做的是辨析观点和事实，这是一项需要训练的能力。一篇文章里，哪些是观点部分，哪些是事实部分，事实部分是否支撑了观点部分。如果事实部分含量很少，通篇是个人观点，甚至充满了我喜欢什么不喜欢什么，什么什么是错误，什么什么又是垃圾等情绪和态度。这种文章，态度大于内容，是不好的。如果一篇文章，总是挑一些极端的案例，放大它们，渲染它们，明显忽视存在其他反例。这种属于幸存者偏差，也是不好的。

好的文章，会平衡内容的分布，增加客观部分，减少主观部分。多使用现成知识、理论或者研究成果，少自己发明，要站在巨人的肩膀上。如果一篇文章，全是引用现成的结论，像抄书一样，确实也没有趣味。还是要有一些自己的态度和观点，但要控制比例，不能太多，前进一小步就足够了。总的而言，高质量的文本，是在事实和理性的基础上，建构更加可靠的知识体系。

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

那么，问题来了，严肃型技术写作究竟该怎么做？其实就是，参考论文的基本内容结构，按照相似的方式展开我们的技术观点。论文的模式支撑了近几百年的科学发展，是严肃型文本的绝佳模仿案例。大家看到这里，是不是回忆起在大学时期写毕业论文的恐惧？其实不用紧张，技术文章也不必像论文那样严格，我们只是粗略地模仿，不是真的要写论文。

a. 摘要/前言(Abstract/Preface)

b. 主题介绍(Introduction)

c. 结构概览（Overview）

d. 内容主体(Main body)

e. 总结/反思(Conclusions/Reflections)

f.  致谢(Acknowledgements)

g. 参考文献(References)

一篇技术文章大致的脉络可以是，先写摘要或前言，概括一下这篇文章要写什么。然后介绍一些基本背景和知识，引导出我们关心的核心问题；写结构概览，描述一下我们内容主体分成多少部分，多少环节，分别解决什么问题；有层次地呈现文章的主体内容，最后做一个总结或者反思，当然也可以加一些未来展望。文末可以添加致谢以及参考文献。至此，我们得到一篇结构完整的技术文章。

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

七、回顾与总结

我们知道了，编程本质上是一种写作活动；技术写作也是程序员日常工作的重要组成部分；参与技术写作有助于贯通实践和表达；技术写作需要找到符合自己当前发展阶段的定位；如何评估技术文章的质量，需要让我们的内容，往更加理性、客观的方向努力；最后，经久不衰的论文结构，是严肃型技术写作的最佳模仿对象。

以上。

 “携程技术”公众号

  分享，交流，成长