书的结构
一本好的技术书,应该是一个前后连贯的整体,具有完整的体系结构。写作是一个从无序到有序的过程。可以把整个写作过程比喻为给一个人梳头发。最初是一头纠缠在一起的乱发,首先把它理顺,然后扎几十个大辫子(每个大辫子还由若干个小辫子组合而成),再把这些辫子错落有致、井然有序的盘绕在一起。
理顺头发相当于理清思路,对知识进行归类。扎辫子相当于写具体的章节,每个大辫子相当于一章,每个小辫子相当于章中的节。盘绕辫子相当于建立不同章节之间的联系。联系主要表现为两种形式:(1)章节之间的参考关系 (2)相关内容之间的对比关系,有些内容看上去相似,但实际有差别,为了不引起混淆,应该进行对比。

以上三个步骤贯穿于写书的整个过程。刚开始动工写作时,只能粗粒度的划分书的章,决定每一章要写的内容,然后按照循序渐进的方式安排章的顺序。在具体写某一章时,还需要细粒度的把章划分为若干小节。在写具体的内容时,如果意识到这段内容与其他章节的内容存在联系,应该随时用文字揭示这种联系。孤立的知识点很容易被遗忘,如果建立了各个知识点之间的联系,这些知识就会在脑海里深深扎根,凡是背过成千上万的英语单词的人肯定都对此深有体会。

尽管以上原理人人都懂,尽管每一本书都有目录,都划分了章节,但是有的书条理清晰,而有的书结构混乱。书的结构是否安排得合理,取决于以下因素:
(1)作者本人对知识的理解程度。如果本人都没有完全搞清体系结构,怎能像庖丁解牛那样,恢恢乎游刃有余?
(2)作者的分类、归纳、概括和演绎能力。这种能力30%靠天赋,70%靠后天的思维练习。对我来说,从Tomcat,到Struts,再到Hibernate,每写一本书,我都必须调动所有的脑细胞,把新的知识体系肢解为章节,然后再把它们联系起来,我的归纳和概括能力在潜移默化中不断提高,当我写Hibernate时,已经明显感受到了这点。
书的内容
如果说书的结构好比房屋的框架,书的内容则好比房屋的具体组成元素。计算机书的内容的形式分为:文字、 表格、图和范例。为了把某种知识讲清楚,常常需要综合使用以上四种形式的元素。
1.文字
文字是介绍知识的最直接的手段。文字表达是否通畅、清晰,是决定书的可读性的重要因素,在这里我想指出两个需要值得注意的地方:
(1)避免英文式的中文语言,由于在写作中需要参考英文文档或书籍,在翻译时很容易受英文的影响,写出不伦不类的中文出来。避免这一问题的手段是,先理解英文文档,接着把它抛到一边,然后到第二天,再完全用自己的母语表达出来。
(2)谨慎的使用各种概念和术语,这是保证书的思路清晰、严谨的重要条件。在如今的计算机领域,新的术语和概念层出不穷,几乎随便拿几个字母组合一下,都代表了一个计算机术语,如J2EE、ORM、DBA、ADO、DAO、CMP、BMP、CMT、BMT、EJB、B2E、B2B、POJO、BO、JDBC、MVC、JSP、JSF....在引用这些术语时,要注意四点:

a.根据书所面向的读者群的技术水平,对一些术语作必要的解释。例如什么叫“轻量级”对象,什么叫“轻量级”封装,这里的轻量级(light weight)到底是什么意思,是否一样?如果想让书形成严谨和清晰的风格,就必须谨慎的使用那些让人感觉含含糊糊的,直接由英文翻译过来的词汇,应该对这些词汇给予清晰的解释。技术书讲究精确、明了,不提倡“只能意会,不可言传”的文风。

b.有些术语有不同的说法,例如关系数据库表中的记录和数据行是同一个概念,在同一段内容中,如果没有作特别说明,最好保持统一的说法。

c.有些术语看似相同,实则有一些差别,如业务对象、持久化类和JavaBean,这些术语并不完全等同,粗枝大叶的作者更本不会去敏锐的区分这些术语,会在同一个上下文中一会儿引用持久化类,一会儿引用JavaBean,一会儿改称业务对象,这会使初级读者看得晕头转向。

d.同一个术语具有不同的含义,例如对象的持久化“状态”和对象的“状态”,这里的“状态”有着不同的含义,应该在文中对此作专门的解释,提高书的可读性。

e.不要总是照搬其他书籍中对概念的解释,必要的话,用自己的语言去定义概念。例如,什么叫事务,什么叫缓存,普通的作者可能会到处查资料,然后从其他书上原封不动的抄过来;而优秀的作者能够根据自己的理解,用更加准确明白的语言去定义概念。
2.表格
表格常用来显示具有并列关系、或者对比关系的内容,能产生更加清晰的视觉效果。
3.图
图是用来形象的描述某种结构、流程或关系的有效手段,通常和文字结合适用。普通的作者不善于自己创作图片,最多从其他地方拷贝一些图片过来。优秀的作者善于把一些复杂的思想用图片的形式表现出来,让读者看了一目了然。
4.范例
范例是帮助读者快速掌握某种技术的捷径。在我的每本书中,每一章都配备了实际可运行的范例,这是我的书受读者欢迎的原因之一。我使用的范例有两种形式,一种是为一个章单独设计的范例,一种是贯穿全书的范例,这个范例包含若干版本,不同版本采用不同的实现手段,这能有效的帮助读者理解各种实现方式的区别和相同点。对于作者来说,设计范例的能力也有一个不断提高的过程,优秀的作者能够密切配合正文的内容,创造性的设计出典型的范例。
书的原材料

在开始写作时,面对的是一张白纸,最后要洋洋洒洒的写出800,000字出来,这些信息并不是原来就全部存储在大脑里的。如果把大脑比作一个输入输出系统,那么以下图展示了大脑在写作时的输入流和输出流。
写书和从事软件开发不同,开发软件时,你只需对技术的某一局部方面非常精通,对其他方面大致了解;但是一本技术书必须提供一个完整系统的知识体系,除了整体的框架,还必须涉及许多细节,比如列举Struts配置文件中每个元素的用法,Struts标签库的每一个标签的用法。因此,在写技术类书籍时,参考其他文档或书籍,或到网上查阅资料是不可避免的。在参考的过程中,作者必须先消化吸收原始材料,然后从中汲取有益的思想,把它融合到自身的作品中。如果作者本人还不完全理解他人的内容,把他人的内容原封不动、七拼八凑到自己的书中,那么整本书前后就会缺乏联贯性和条理性,不能构成一个完整独立的知识体系,让读者看了不知所云。

书的润色

对书进行润色就好比对房屋进行装修,使书的形式能完美的反映书的内容。当完成书的初稿后,需要对书稿复查好几遍,复查的过程也就是对书润色的过程。在复查的过程中,主要负责以下工作:
- 修改笔误和错别字。
- 核查内容的正确性。
- 进一步推敲措辞用语,直到它能最清晰的表达特定思想。
- 如果内容还不完整,可以再扩充内容。
- 从书的全局出发,对书的结构进行协调,使它循序渐进,前后连贯。

根据我的经验,每复查一边,我都会对书稿作一些改动,第一次复查时改动量最大,以后逐渐减少,这是一个精益求精的过程,直到基本上我觉得满意时,就可以向出版社交稿了。就像有人说房屋的装修无止境一样,书的润色也是无穷尽的。书的品质只会逐渐趋向于完美,但是永远不会达到完美无缺的极限。对书的精雕细琢会达到什么程度,不仅取决于作者的写作水平,更取决于作者的写作态度。
书的深度
正如一位读者所说,运用性的计算机技术都谈不上高深,对此我很认同。当你接触一种新技术时,在对它一无所知的时候,可能会觉得它很难,神秘莫测,可是一旦熟悉并掌握了它,就会觉得不过如此。优秀的计算机书籍应该力图向读者展示技术的浅显易懂的真面目,这包括从书的结构和书的内容两方面去下功夫。当读者读不懂一本书时,如果误以为是因为技术本身非常深奥,难以理解,那就错了。只要读者的理解和领悟能力不是太差,往往是因为书本身写得不好,比如结构不清,语言晦涩,各种不加解释的新名词、新术语到处乱飞,使读者看得着时费力。
我写的Struts和Hibernate都清晰明了,即使是初学者也能看懂,当他们看懂了书后,会大有收获,并且觉得技术原来并不难。不过也有少量读者,已经习惯于被那些看似深奥的书搞得战战兢兢,当他们轻轻松松看完我的书后,却运用以下错误的逻辑条件,再加上错误的逻辑推理,得出错误的结论,说我的书通俗易懂,但缺乏深度:
看不懂的书 -->是有深度的书
(反之)看得懂的书 -->是没深度的书
作者:孙卫琴
写作时间:2005-4