碎碎念之「技术文档写作风格」

这里的技术文档，包括在软件开发中常见的需求文档、设计文档、操作手册等等。它们共同的特点是，需要用简明扼要、理性准确的语言，把事情说清楚。不管这些事情是在说要做什么软件、怎么做软件还是怎么用软件。

技术文档和其他文档的区别，通过下面这张 Twitter 上的图，可以形象地显露出来。

Karl Kovacs @karlkovacs

写个人邮件，不管是出于感情、礼貌还是习惯，难免会有冗余、要客套，也不太注重逻辑性。而技术文档最重要的功能是，清晰准确地传递信息。并不需要充满感情、也不需要文采。所以，从技术文档的标准看，上面那封邮件就显得不够清晰明了。

改成下面那样，虽然索然无味，但一目了然，扫一眼就得到了全部重要信息。我自己测试，读完上半部分需要 18 秒，下半部分需要 4 秒。技术文档要被反复阅读，理解成本低当然是要追求的。

技术文档没有风格就是最好的风格，或者说采用实用、朴素的风格就好，不需要其他风格来体现作者的品味，向读者呈现不偏不倚的事实才是目的。而且，一个项目中，技术文档往往是不同角色的多个人来写作的，只有朴素的风格是最容易达成一致的。

什么是朴素的风格？以用词为例。如果我们是在写博客，经常会对同一个意思更换各种用词，防止大家觉得枯燥无聊。但如果是写技术文档，我建议你坚持不要换词，甚至对一个团队来说统一词汇表是很早就要重视的事。

也不要用一些只有技术人员才懂的黑话，而是要用业界公认的正式术语。有时候甚至这些黑话本身就是一种认知错误。比如，在游戏圈招人经常听说「粘包」这个概念。我刚听到的时候，一脸懵逼，做这么多年技术，这是个啥？粘豆包倒是吃过。后来才发现完全就是没仔细搞懂 TCP 犯的错误。

所以，写技术文档重要的是：用简单的话，说明白事，在意读者的阅读成本。这里有个实操指南比较系统，很实用，推荐。