1. DocBook 初体验

1.1. 是否似曾相识
1.2. 文档是这样完成的

如果你是一个软件开发人员,是否对撰写文档深恶痛绝?为应付工作而写的文档,往往不加维护,且难以维护,远远不能反映软件设计的实际情况,成为文件服务器中的垃圾。

如果你是一个文档工程师,经常要面对一个文档有多种输出格式,如 Word文档,PDF格式,HTML格式的文档。如果你要长期维护每一种格式的文档,又能保障它们的一致性,那么你真是太伟大了。

软件开发引入版本控制,使得多人协作成为可能,也使得软件开发走向规模化,摆脱手工作坊的开发模式。但是文档的撰写和维护,你做到了版本控制和多人协作了么?

DocBook正是针对上述顽症的一剂解药。DocBook 作为风行于开放源码世界的一种文档撰写格式,已经成为很多组织和公司撰写技术文档的事实上的规范。DocBook 提供了一种基于SGML/XML的、面向语义、面向结构、纯文本格式、可版本控制的文档撰写模式,它打破了传统的、面向表现的、所见即所得的、基于私有格式的文档撰写模式。基于SGML/XML的面向结构的文档,使得 DocBook 格式的文档,成为一种真正的万能格式的文档,几乎可以转换为任何一种文档格式。而属于纯文本范畴的 DocBook 文档,更可以利用版本控制软件,实现多人协作维护。

然而,国内了解 DocBook 的人还不多。当然,这也是由于国内参与国际性的开放源码开发的人太少有关,更多的人还是喜欢闭门造车。技术文档的撰写,也还是停留在商务文档的写作模式之上,注重形式,忽视文档的可维护性。大家在享受 Word 的所见即所得的方便的表象的背后,是文档更新的困难——难以多人协同维护,文档互相覆盖,乱糟糟一团。到头来,文件服务器中是文档堆成山,但大都由于过时而严重的贬值了。

任何工作都要有文档记录,这不应该成为一句口号,想要建成百年老店的中国软件企业,要重视知识的积累。利用本书所介绍的 DocBook,撰写可维护文档,让任何工作都有文档记录不再是梦想。DocBook 更是个人知识积累的工具,愈早使用 DocBook,愈早获得知识持续积累的快乐,享受完成传世之作的成就感。