关于编写参考手册的思考¶
自从本月月初完成了《Redis in Action》的翻译工作之后， 我就开始了新书的写作。 这次的新书是一本参考手册类型的书， 篇幅比较多， 需要写的内容也比较多， 不过内容还是非常有趣的， 所以整个写作过程还是非常愉快的。
因为我是第一次写参考手册方面的书籍， 所以在这方面做了一些思考， 希望能把这本书写好， 而这篇文章就会和大家分享一下我关于如何编写参考手册的想法。
总的来说， 我认为一本好的参考手册应该是完整的、精确的、及时更新的并且有所取舍的， 接下来的几个小节将分别对这几个方面进行介绍。
参考手册的定义¶
一本参考手册就是关于一个软件、一个系统或者一项技术的完整描述， 这种描述可以是针对某一方面的， 也可以是针对整个软件、系统和技术的。
举个例子， 对于 Python 这门编程语言本身来说， 《The Python Language Reference》就是它的参考手册。
又比如说， 对于 Redis 的命令来说， 《Redis Command Reference》就是它的参考手册。
除了在线的手册之外， 有一些参考手册也是以书本的形式出现的， 比如说 《C: A Reference Manual 》 、 《UNIX 环境高级编程》 、 《UNIX 网络编程》 、 甚至 《算法导论》 也可以算是参考手册。
好的参考手册应该是完整的¶
参考手册的一个最基本的要求就是完整， 这是参考手册安身立命之所在： 它应该包含详细的、齐全的信息， 书中应该对所有必需的知识点进行覆盖， 并包含那些读者想要在参考手册里面找到的信息。
举个例子， 如果一个软件有两百个必需的知识点， 那么参考手册也应该对这两百个知识点进行介绍， 缺一不可。 又比如说， 如果一个软件有三百个重要的特性， 那么参考手册也应该对这三百个特性进行介绍， 甚至超越这三百个特性， 对整个系统进行必要的描述。
当读者翻开一本参考手册的时候， 他应该可以找到书本关于某个特性的详细描述， 如果参考手册不能做到这一点的话， 那么它将是失职的、不合格的。
与此同时， 因为参考手册的作者必须对整个系统的每个部分都有所了解， 这样才能写出对系统进行完整描述的参考手册， 因此编写参考手册将是一件非常繁重而辛苦的工作。 要描述的系统越大， 参考手册的篇幅也会越大， 作者需要花费的功夫也会越多。
好的参考手册应该是精确的¶
一本参考手册应该是精确的， 它所描述的信息应该是准确而没有歧义的， 它的例子应该是有效的、具有示范性质的。
要让手册的内容保持精确， 其中一个办法就是假设有人在参照你的手册编写实现（implementation，比如编程语言解释器）， 这时你就必须写出精确的手册， 描述好程序在不同情况下产生的不同行为， 针对什么输入会产生什么输出等等。
让手册保持精确的另一个要点在于示例的选择： 作者在给知识点添加例子的时候， 应该尽量选择简单的示例， 示例里面应该只描述必须的信息， 并且这个示例应该是自包含的， 它不需要去引用其他信息； 示例本身带有良好的注释， 确保读者可以理解这些例子； 诸如此类。
好的参考手册应该是及时更新的¶
一本参考手册应该是及时更新的， 当读者阅读它的时候， 看到的应该是与最新版本同步的信息。
举个例子， 如果一个软件出了 2.0 版本， 那么它的参考手册应该也是讲述 2.0 版本的； 又比如说， 如果一个软件出了 3.0 版本， 那么它的参考手册应该也是讲述 3.0 版本的； 诸如此类。
读者永远都希望自己能接收到最新出炉的信息， 他们肯定不希望把自己的宝贵时间浪费在阅读过时的信息上面， 而参考手册的其中一个目标就是满足这一需求， 但是要做到这一点并不容易。
首先， 及时更新对作者来说是一个严峻的考验： 当软件释出一个新版本之后， 作者必须研究新版本的新特性， 了解新版与旧版之间的兼容问题， 软件本身发生的变化等等， 并把这些信息通过自己的语言写入到手册里面， 而这一切必须在尽可能短的时间内完成。 当新版本的修改非常多的时候， 及时地更新手册就会变成一项难度非常高的任务， 将给作者带来非常大的压力。
其次， 及时更新对于书本的发行商来说也是一个严峻的考验， 对于传统出版社来说， 更是如此： 一般来说， 作者在交稿之后， 出版社都要对书本原稿进行编辑、排版、印刷， 最后再将印刷好的书本运送到全国各地的书店以及各个网上书店的仓库上面， 而这个过程少说也需要几个月的时间， 即使作者在新版释出之后第一时间进行写作， 纸书的制造流程也会令书本的新鲜度大打折扣。
另一方面， 如果通过电子书手段发行参考手册的话， 我们就可以把发行新版手册所需的时间大大减少： 根据选择的电子发行商不同， 这个时间可以是一个月， 一周， 几天， 甚至即时发行也是有可能的。
因此， 对于打算编写参考手册的作者来说， 通过电子书来发行自己的手册应该是一个不错的方式。 如果一定要通过纸书方式来发行， 那么就应该提前与出版社商量好发行时限（交稿之后多久才会完成整个纸书制造流程？）、发行新版的间隔（半年更新一次？一年更新一次？一年半更新一次？）等等。
好的参考手册应该是有所取舍的¶
最后一点， 也是我认为编写参考手册最难的一点， 那就是对内容进行取舍。
正如本文之前所讲， 一本好的参考手册应该是完整的、详细的， 但是与此同时， 参考手册必须有所取舍： 如果一本参考手册的内容太过繁琐、太过沉迷于细节， 变成了一本难以阅读的“字典”甚至“天书”， 那么它对于读者将是没有价值的。
一本好的参考手册应该在读者能够接受的篇幅范围之内， 填充最有用的信息， 保证内容的稠密程度， 并在必要的时候保留一定程度的细节， 但是不要过分地深入， 要懂得适可而止。
最近在写作的时候， 我思考得最多的就是“这些知识要写进书里面吗”、 “这些知识看上去比较难懂，有没有更好的办法来简化它们呢？”、 “这个知识点是必须的吗？如果移除它的话会怎样？”， 诸如此类的问题。 思考这些问题真的非常伤脑筋， 但是我相信这些努力最终都会有所回报 —— 我希望读者将来在阅读这本书的时候， 可以发现对于他们来说真正有用的东西， 而不是一堆包含了大量无用细节的垃圾。
对于一本参考手册来说， 它没有说什么和它说了什么一样重要， 有时候前者甚至会比后者更重要。