程序员的中文写作指北

作为一名程序员，我们的本业让我们绝大多数的时间都在埋头写代码。

但很多时候，不管你在自己创业还是在公司搬砖，光是代码漂亮是不够的。很多时候，特别是当你需要展示你的想法或者说服别人的时候，好的文章、设计文档至关重要。

比如说，如果你在公司搬砖，在新做一个稍大型一点的系统的时候，设计文档写得怎么样可能直接关系这个项目是不是会被孵化。而如果你在自己创业，能写出好内容则更加重要——毕竟你要说服陌生人购买你的产品、使用你的服务，首先你的潜在用户需要通过你的清晰表达来了解你在做什么，你的产品能帮他们解决什么问题。

就算你对写风花雪月不感兴趣，那你总得偶尔写一些技术文章、交接文档。就算纯技术相关的内容，也需要刻意地练习，才能写得清楚漂亮。不知道你有没有注意过，多数优秀的项目不光代码优秀，文档也非常棒。这里说的漂亮不光是排版规整，行文也流畅且自然。

不幸的是，作为程序员的我们，一旦文章不漂亮，第一直觉想起来的事不是调整文章，而是调整 CSS 和页面布局。页面怎么摆固然重要，但文章本身如何，才是根本。毕竟你的读者都是人，而不是读 html 的计算机。

之所以我把这篇文章标题起为“给程序员中文写作指北”，是因为两个原因

• 我自己是程序员，我也不知道怎么写小说，但技术文章我写了不少。因此我的观点只适用于程序员群体
• “指北”而非“指南”是因为这些也只是我自己的经验总结，不同人肯定有不同的意见。而太主观的观点在我看来，不适合写一份“指南”作为黄金标准

正因为此，如果你读到与自己习惯完全相左的内容，不用担心，也许那样的习惯更适合于你。但总体上，有一些放诸四海皆准的原则，比如段落不宜太长，比如不要中英标点混用等等。总之，希望大家各取所需，根据自己情况调整就好。

本文中我会从以下三个方面进行总结，如果有更新，我会直接更新到文章中，也欢迎关注我们的博客和公众号（HiXieke）

以下是正文

关于内容的建议

---

很多人有写博客的习惯，中文圈也有非常多优秀的博客和公众号。在我看来，绝大多数文章之所以吸引人，并不一定在于行文本身多出彩或者排版有多好看，对读者最重要的首先应该是言之有物。

如何做到写技术文章时言之有物呢？

在我来看，要做到言之有物，最主要的方法就是：你应该是你所以写的内容的专家。

举个例子，不管你文采再出众，如果写一篇文章叫《Java深入浅出》但是内容却浅显得只讲到 Java 的语法，试问，你的读者如何感觉你的文章有吸引力并能继续读下去？

但要做到言之有物是个长期的过程，写文章的感觉需要一步步地培养，只要你能坚持下面几个建议，长期会有奇效

notes

动笔前先把想法理清楚

在日常交流时，有时候我们感觉讨论时论据不足，感觉心虚，通常会尝试以下几个方法敷衍过去

• 用一个相关但不一定有逻辑关联的理由搪塞

但不幸的是，在写作时这些小技巧完全不适用，因为你的读者有足够的时间，反复揣摩你写下来的话语。

因此，如果你需要把文章写清楚，必须先在脑子里，把逻辑、思路理顺，把起承转合思考好。用对话的逻辑来写作，特别是技术文章，是行不通的。

在亚马逊，贝索斯要求所有高管在跟他开会前写一个6页详实的纪要，开会一开始大家先默读完纪要再开会。而这样的要求，事实上也是在要求与会者不要瞎扯，把观点都书面写下来，逻辑必须自恰，这样才能做到讨论的时候言之有物。

理一个贯穿全文的提纲

如果你的文章是关于一个非常具体的技术实现，那么大概率你不用担心太多，因为你的写作范围就限定了你需要把文章聚焦在那个技术实现上。

但如果你需要写一个比较大的技术系统，甚至于一个更泛化的理念（比如你想要在公司推动测试驱动的开发流程），那么你需要把文章的提纲理得非常明晰。很多文章稍一长，内容就开始飘忽不定，而这会让你的读者找不到重点。

我有一个非常方便可以检验的办法：你可以把你的文章内容全删掉，而只看二级、三级标题，应该能让别人大致知道你在说什么。

用数据、例子和论据来表明观点

读过高中应该都感觉熟悉，为了写议论文，谁还没背过爱迪生的发明呢？

在写技术文章、系统设计甚至技术博客时，如果有数据支撑，那再好不过了。

举个例子，你在一家提供教育视频下载的公司，希望推进设计一个分布式视频缓存系统。如果这时候你能够总结出在疫情前，每周的视频下载量的增长，以及因为疫情，前几周的视频增速，核算出一个合理的 3 个月后的系统需求，那么这个数据比你的文章再出彩都好用。

而例子可以极大地简化读者理解的难度。如果有合适的例子，在合适的地方用上会有非常大的帮助。比如说，如果上一段我只是在干巴巴地说明，有数据支撑时应该用数据，文章读起来会晦涩不少。

做大量研究

前面说过，如果你需要言之有物，最好的办法是变成这个领域的专家。

当然，如果我们的文章都是技术文章，相信你对于要写的技术内容已经有了一些了解。但旁征博引一下看一看前人怎么做的、怎么写的，总没有坏处。如果你看的信息够多，多数情况下，光是总结都可以写一篇非常详实的文章。

research对写文章的重要性

而如果你通过研究别人之前写过的内容，加上你自己的理解，大多数情况下出来的文字都是生动而丰满的。

比如说，在写《优秀 REST API 设计指南》这篇文章的时候，我前后参考了 20 多篇国内外程序员写的文章，读了 Stripe, GitHub 的REST文档，才写出这样一篇建议。如果你对 API 设计感兴趣，推荐阅读。

同样的，即使是专注技术的文章，也需要花大量时间确认事实和多处互相参照。我们在写正在进行的《Elastic 初学终极教程》的时，每一篇教程大概需要花10个小时左右做非常细致的研究。因为即使已经做了很多年搜索引擎，有很多细节也需要额外注意，否则写出来的文章会模棱两可。

关于排版的建议

---

说到排版，相信大家都有类似的经历：即使一本好书，或者一篇好文章，如果排版实在让人觉得不堪入目，可能它连开始被读的机会都不会有。

同样的，当我们在写文章时，版面如同给人留下的第一印象，是极其重要的。

技术文档相比诗歌、小说散文等其它内容的文章，需要注意到排版的地方更多。原因主要是在技术文章中，经常会有中英文（文字和代码）、全半角标点切换、代码块等等复杂的情况。关于标点的格式，这里主要参考了《写给大家看的中文排版指南》。

关于英文排版的部分，推荐阅读《Blog Format》。而关于代码的部分，主要是我自己写的。

中英文标点

中文排版中的标点，应该统一用全角

中文文字比较大，如果用英文的半角标点读起来会让人感觉文字时大时小，同时分隔不明显。请对比：

错误示例:这篇文章写得还不错,我强烈推荐给你看一下!看不看不重要,跟着学才好

推荐示例：这篇文章写得还不错，我强烈推荐给你看一下！看不看不重要，跟着学才好

空格的使用

1. 在行文中，中英文之间应该加空格。请对比：

错误示例：我的公众号是HiXieke，关注我吧！我的粉丝现在有567个了呢！

推荐示例：我的公众号是 HiXieke，关注我吧！我的粉丝现在有 567 个了呢！

1. 英文标点结束时，需要加空格。请对比：

错误示例：Here's to the crazy ones.The misfits.The rebels.The troublemakers.The round pegs in the square holes.

推荐示例：Here's to the crazy ones. The misfits. The rebels. The troublemakers. The round pegs in the square holes.

顺便说一下，英文标点后加空格是通用的英文写作格式，在写书信、email等所有地方都适用。

1. 全角标点与其它字符间不加空格

错误示例：我觉得你这煎饼果子好吃， Elon Musk 前阵子不是也吃过

推荐示例：我觉得你这煎饼果子好吃，Elon Musk 前阵子不是也吃过

1. 注释符前后应该至少有一个空格

错误示例：print("Hello world")#你好世界

推荐示例：print("Hello world") # 你好世界

CSS和HTML

专有名词首字母大写并遵循协定

对于表示专有名词的单词，除了在代码中作为变量名需要遵循变量命名规范外，其它地方均需要按协定来确定大小写。比如说：

错误示例：javaScript 是前端语言

推荐示例：JavaScript 是前端语言

类似的名词还有：GitHub, Angular, React Native

如果不确定的话，可以参考Wikipedia，Wiki里的命名都是非常规范的。

关于行文的建议

---

技术文章、博客文章忌用复杂的长句和重句。

主要原因是，当句子一长我们的大脑需要花太多的时间来理解这个句子的字面意义而不能专注于理解这个句子要传达的内容因而这与我们的目的完全南辕北辙。

上面这个句子读起来就非常痛苦了，换位思考一下，如果你的文章这么写读者该多痛苦。我建议，句子的长度应该控制在15个词以内，如果有长句的话，应该用标点切分为较短的句子。同时在重复率不高的情况下，尽量用简单的词汇。上面的句子可以改写为：

主要原因是，当句子一长，我们的大脑需要花太多时间，来理解这个句子的字面意义。而此时我们的大脑无法专注句子本身要传达的内容，这与我们的目的完全相悖。

如果有条件，尽量在文章中插入一些与逻辑和表达的内容相关的图片。

图文并茂不光可以让你的读者读起来更轻松，更让你有机会用图表、gif 或其它丰富的媒体形式来表达你的观点，一举几得。同时，如果你的网站需要流量，搜索引擎对相关的图片和视频会增加权重，有利于你的搜索流量增长。

如果你担心版权，可以考虑用一些无版权的图片库，比如我们几乎所有的图片都来自于 Unsplash.com。

注意起承转合

即使技术文章的主要写作文体更偏向议论文，但在写作时也需要注意起承转合。

如果你需要像本文一样，列出一系列观点，将这些观点以合理的逻辑串起来也是非常重要的。

在文章结构上，我通常会采用总、分、总的结构。

总 - 即文首先告诉读者会读到什么，如果读者不感兴趣的话可以省下来读一篇文章的时间，而如果感兴趣的话正好是个好引子。

分 - 即分散表达需要表达的观点，比如在本文中，即三个部分：关于内容、关于标点和关于行文的三块建议。

总 - 最后总结文章，你要假设读者并没有时间详读全文，但这里的总结可以让读者能在 10 秒内仍然知道你在这篇文章里表达了什么

引用丰富的链接

把你引用的内容放在合适的位置，不仅是对被引用文章作者的尊重，也方便你的读者继续阅读下去。

Links

千万不要觉得引用文章会让人觉得你只是在观点抄袭，事实上只要你有提出新鲜的观点、论据甚至只是更规范地总结了一篇文章，你的读者也会非常感激你的。

同时引用丰富的链接还可以帮助搜索引擎确定你的权威性——你不光文章写出来了，还指向了靠谱的参考文献，因此搜索引擎也会觉得你这篇文章的靠谱程度很高。

能读到这里的都是英雄。即使你从中间跳到了这里，也希望我的文章可以帮助你以后的博客、技术文档写作。

总结一下，这篇文章里，我们讨论了中文技术写作的一些需要注意的地方。我给出了一些关于内容上、排版上和行文上的建议。长期坚持，相信你也可以写出漂亮的文字，帮你升职加薪到达人生巅峰。

我们会继续在我们的博客和公众号上（HiXieke，近期会更新）发布新的文章，包括程序员成长、技术讨论和我们的创业故事，欢迎关注。

如果你也写博客，欢迎给我邮件交换友情链接，或者如果有帮到你，请直接链到这篇文章，帮更多的人看到。