我有时会想，要不要写一写关于技术写作（以及如何不写）的东西。恰好最近有人发邮件向我请教，所以这篇文章既是我过往思考的集合，也是那封回复的提炼。
任何写作，和许多人类活动一样，都是天赋和技能的结合。天赋，你要么有，要么就没有；而技能可以学习、提升乃至精通。天赋很难解释，因为它大多是无意识的。我无法告诉你，我脑海中那些模糊的念头是怎么变成屏幕上的文字的——它就是发生了。不过，我能告诉你一些该做的和不该做的事。
技术材料有很多种。我主要写文章、期刊论文、Unix风格的手册页、API文档，还有几本书。所以我的建议只适合这些类型。我原本觉得下面的建议都是明摆着的，不该多此一举；但看到那么多糟糕的技术写作后，我觉得还是有必要讲。
这些建议可以浓缩成几个要点。你的写作应该是：
- 不同的
- 格式良好的
- 正确的
- 精确的
- 完整的
- 一致的
注意，这些建议是从做自己的技术写作的角度出发的，也就是写你想写的东西。如果你的职业就是技术写作，那么日常工作是按别人的要求来写，而且很可能受到内部风格指南的约束。那我的建议就不适合你了。
不同
在真正动笔之前，先想想你要写的东西到底值不值得写。这世界真的还需要再一篇介绍C语言基本数据类型（像int和char）的文章吗？
不过，如果你准备讲得特别深、展示一些冷门的用法，或者某种创造性的应用——总之，写出一些不一样的东西——那就放心写吧。
格式
对我来说，写的东西应该排版得当，这本来再明显不过——可我却看过太多反面例子。格式糟糕的时候，读起来会刺眼，整个阅读都变成一种折磨。我甚至不理解怎么会有人把排版一团糟的东西发出来。难道他们自己看不出这东西“好难看”吗？（我怀疑是有没有审美基因这回事，有些人可能没有。）
反过来，如果格式很好，排版本身会退到幕后，你几乎注意不到它，读起来就很轻松。
对于涉及代码的技术写作，代码得用另一种字体，一般是等宽字体，通常用Courier。
这里要用“字体排印设计”（typeface）这个说法才准确。typeface是字母和符号的样式设计，而font是特定大小（比如10磅）和风格（比如粗体）的typeface。Courier、Helvetica和Times Roman是typeface；Helvetica 10磅粗体是font。在技术写作中，分清这两个概念，有助于和设计师沟通，也更显专业。
排版不只是选字体。段落的空白、标题的层级、列表的使用、代码块的缩进，都属于格式。好的格式让文档一目了然；坏的格式则会把思维打散。如果你原本的观点就不清晰，那么混乱的排版会让它彻底不可读。其实，很多写作者不是内容不行，只是被形式拖垮了。
如果觉得自己的审美不够用，最简单的做法是参考成熟的排版惯例：保持一致的段落间距，统一标题样式，用字号对比来区分层级，代码严格使用等宽字体。做到这些，即使内容平实，读者也会觉得你专业。
总之，好的技术写作会让人把注意力放在你要传递的信息上，而不是文档本身的装修上。如果你需要不停地为格式分心，那就说明格式还没做好。
热门跟贴