撰写代码是程序员的本职工作，但编写文档时至今日依然常常遭到忽视。纵有高人曰过，优雅的代码是最好的文档，但先不说多少人的代码能达到这般境界，许多事务并不能仅靠代码本身完成。例如：用户文档，不能倚赖用户去阅读代码后再使用你的系统；设计文档，需要快速纵览项目时并无闲暇去阅览数万行代码；需求文档，乙方不可能按着你的 API 接口声明猜测你的意图……然而，几乎每一个程序员都被文档的匮乏深深伤害过。

于是，许多意识到重要性的程序员开始着手编写文档了。可惜的是，编程与语文这两项技能似乎常常互不兼容。大量程序员的写作水平不尽人意，写出的文档也不堪卒读，让人或云里雾里，或视觉疲劳。最坏的情况是看了还不如没看——有错误的地图甚至坏过没有地图。每次面对比遗留代码还深奥的文档时，我都感觉自己又在折寿。

是程序员的大脑普遍缺乏语文神经吗？私以为，还是十二年中小学语文教育以分数为导向、缺乏实用的「语文技能」教学所致。语文课堂上，为了分数，学生被灌输的是「鉴赏」（其实就是模式识别加套路背诵）和「写作」（其实就是八股文加更多的套路背诵）。在阅读理解中，学生读懂出题者的意图，投其所好；到了写作里，学生搜肠刮肚，将一堆名人名言砌入起承转合。选择程序员为职业的人，多数本就缺乏诗词歌赋的天赋，再加之从未习得（实用的）写作技能，自然难以奢望在真实环境里有何等写作能力。

扯得有点远，但我想说的是，适用于真实写作的实用技能是存在的（也可以称之为有用的套路）。尤其是对于并不要求多少创造力的各类程序文档而言，能够简洁、明了、完整、优雅地表达意图，便已实属优秀了。

我自认语文能力算不得优秀，但还算从各路捡到过一些技巧；加之作为程序员，在一年的实习里就已见到太多惹人揪心的文档。于是我想在此分享一些程序文档写作的技巧与经验，就当是抛砖引玉。如贻笑大方，还请多加指教、手下留情。

在此先说明一下这些方法的总目的：

1. 优雅美观。好的文档应当赏心悦目的，从排版至字里行间流露严谨而可靠的气质。
2. 平易近人。好的文档读起来应该是高效而不累的，即无繁冗的词句，也没有晦涩的字词。
3. 清晰明了。好的文档要组织清晰，将符合使命的信息完整地传递给目标用户。

另外，为预防一些歧义，需要在此声明一下适用范围：

1. 仅适用于电子书面文档。口头交流、IM 沟通、纸张书写因其不同特性，并不建议直接套用本系列文章中的所有方法。
2. 仅适用于正式的说明文。文艺创作是一个复杂的领域，我不敢班门弄斧，也不愿让固化的套路破坏文学的优美。

这篇文章里，我们先来看看我认为最重要的那些守则。这些守则提纲挈领，或可普遍适用。

排版

推荐文档：《中文文案排版指北》

内文排版是安排字词段落的艺术设计，对于书写文档的程序员而言，发挥的余地其实不多：我们编写文档的环境通常并不允许我们微调行间距、页边距等微妙的属性。

但即使是纯文本的写作环境下，依然有一组排版原则值得每一位写作者遵循。这组原则被诸多文章解释得颇为清晰，本博客不愿重复网上能轻易搜到的东西，所以烦请转至上方链接观看这篇我认为相对阐述到位的指引。

其实这组规范许多人早已有所耳闻，可能也学习过，但并不总是记得运用，或是不能适当地使用。知其所以然，方能运用自如。因此在这一节，我将介绍一下自己对某些规范的理解。

留白

加空格，或许是这套规范中最著名的一条。程序员可以分为两类，一类会在全半角词语之间加空格，另一类不会。其实与诸多规则一样，加空格不是目的，只是实现留白的一种手段，而留白的目的，又是为了美观易读。

在罗马字母书写的语言中，空格是非常常见的分词工具（八卦一下，欧洲直到八九世纪才在书写中普遍使用空格）。这一书写规则很好理解：避免歧义的同时，还能突出显示单词的形状（拼音语言单词的辨识度常来自于其边缘形状）。

而汉字，因其历史原因（如文言文中通常一字一词），从未引入空格等分词符。于是在中英混排时，就会出现一个疑问：不分词的中文和分词的英文之间，该不该加入分词符呢？

应当与否，这点早已有所定论。只要看看 Office Word 默认的排版引擎便知：即使是上古 Word，也会在全半角词语间自动加入空白间隙。而翻阅一些上世纪的老书，也能看到这样的痕迹。在我看来，适当的留白有助于语言思维的切换，也是对西文以空格分词的惯例的遵循，同时留白让挨着中文的单词相对独立，也更易辨读。

在中英之间加入适当的间距会提升可读性，这几乎是公认的。但如果仔细观察，会发现 Word 与书籍的排版中，留白并没有达到一个空格的长度，而是略短一点。是的，这才是混排留白的最佳距离，而加入空格来实现留白，不过是排版引擎不争气，写作者迫不得已的越俎代庖——但还是好过完全没有间隙。

非专业文字处理的排版引擎几乎都不会自动留白，这一点被人诟病已久，但我们确实可以看到进步的希望：Apple 最新的系统应用已经支持在中西文间自动留白，CSS 利用 text-spacing 属性指定留白规则也已进入提案，部分 app 如微信还自研了一套排版引擎实现这一特性（虽然经常爆出溢出漏洞）。

留白本应是排版引擎的事，但在其普及之前，还是给英文和数字的两端加上空格吧。

一致

一致性可以分为两类：标点符号与文章语言一致、专有名词与官方形式一致。

标点符号一致，要求写作者在中文文章中不使用半角符号，除非是整句地引用。而专有名词一致，则要求写作者使用官方的拼写和大小写形式，比如某知名交友网站要写作 GitHub，而非 github、Github，更不能是 gh。（说实话，我很少看到能拼对 GitHub 的程序员。）

这一套规范看似繁琐，但实际上对整篇文档的「气质」相当重要，一旦遵守，就能极大提升读者对文章及其作者的第一印象。一篇标点错乱、大小写涣散的文章，会在直觉上给人极不专业的感觉；而标点严谨，专有名词使用考究的文章，会自然而然地流露出正式、可靠的气息。

这一点，我时常在别人问我简历或者 PPT 的改进之处时指出。对于程序员而言，简历是用来体现自己专业技能和严谨态度的迷你文档，HR 和历位面试官对你的第一印象都来自于它。PPT 与之相仿，往往用于展示成果或推销想法，目的也是为了让观者接受其内容。在诸多场景中，正确的标点与拼写形式能彰显作者严谨可靠，也会随之提升内容的可信程度。

一致性是对形式的追求，但别人对内容与你的直观印象往往来自形式。

语法

文档里自然语言的语法错误，就像粥里的一颗沙子，咬到总会膈应一下。中学语文教学还是有用的，至少其病句修改能给我们建立汉语语法的初步印象，可惜完整语法就毫无立足之地了。尽管没有婴儿学说话前要先学语法，但作为写作者——文字内容的创造者，还是需要明确了解一些语法知识来指导我们的遣词造句的。

语法的掌握非一日之功，尤其是离开课堂以后，更难有动力与时间研究一门语言的形式（哪怕是自己的母语——但这也许更增进了虚假的自信）。其实，在病句题中学到的知识已经足以应对大部分的语法错误，只需要对自己写出来的东西多加回顾，诸如主语缺失一类的错误也不难改正。虽然语法基础是写作的重要技能，但本系列并不会详细讲解。

相比语法错误，更常见的是一些算不上错的语法问题，但这些问题会导致生硬的表达方式。这些问题多半是学习外语所致：在成长过程中，我们的老师很少会传授汉语语法（我有幸遇到了两位愿意讲解的语文老师，在此感谢他们），却在英语课上大量灌输异国他乡的句子成分、短语构成。不少人会在潜意识里将英语的语法知识迁移到汉语的空白中，造就了所谓的「英式中文」，写出来的东西繁琐别扭，不够流利自然。这类问题会在后续的文章中详加阐述。

审丑

这一点针对的不是文档，而是每一名作者自身。不懂得美的人无法创作出美，不懂得丑之所以为丑的人，也很难避免制造出丑。知道什么丑陋、为何丑陋，学会对之憎恶并试图改进，而不是漠然无视，才能让所创作之物趋于「美」。

审丑的第一步，是知丑为丑。比如看到一篇千疮百孔的文档，里面充斥着中英乱排、颠三倒四，我们要知道这篇文档是丑的；看到一个句子主语缺失、标点错乱，我们要知道这句话是丑的；看到某个单词大小写紊乱，我们要知道这个词是丑（至少不美）的。只有知丑为丑，我们才不会对房间的大象视若无睹，放任其继续存在。

审丑的第二步，是知丑为何为丑。其实大部分的丑，我们都能凭直觉感知，却难以清晰认知。某句话读起来怪怪的，但为什么呢？如果缺乏一套规则和理论，我们很难从感性认识提炼出理性知识，遑论改进与避免的方法。下次可能重复一样的错误，却不知结症何在、如何是好，最后也只能放任自流。倘若我们知其为何丑陋，便能有意识地避而远之。

不仅文档如此，编写代码也是相似的道理。没有完美的代码，每一个项目在生长过程中都会不可避免地滋生异味（code smells）。如果是一名对各类代码异味、反模式毫无知觉的程序员，可能根本无法意识到代码中的种种问题；或许能从程序运行的表象中发现一些迹象（如运行缓慢、修改代码困难），却不知根源所在。但如若了解各种代码的丑陋，并知其为何腐臭之后，我们便能对症下药，用谨慎避免新坑，以重构消化存量，而不是继续无知地在布满焦油坑的丛林里乱撞。

没有认知就难以思考，也无从应对。我不仅希望本系列短文能种下一颗强迫症的种子，还能介绍一番文档里常见丑陋之处。这样，下次看到（或不小心写出）这样的瑕疵时，就能够心想「噢，这里这么改会变得更好」。