天下文章
（王咏刚 2004 年5 月）
1 问题引入
程序员最怕写文档，这是一个放之四海而皆准的真理。
唐朝大诗人贾岛曾经说：“二句三年得，一吟双泪流”。连
贾岛这样的天才，写两句话都得花上三年时间，好容易写
出来了，没准儿还要痛哭流涕、悲伤欲绝，何况你我这些
缺乏艺术细胞的程序员呢？
当然了，技术文档十分重要，好的文档不仅可以保证
项目质量、加强交流和沟通，还兼有向老板展示工作成果
以邀功请赏的效用。但想想那些为了应付ISO9001 外审，
或是为了保住CMM3 的金字招牌而拼命赶写文档的程序
员吧——面对需求说明、用例描述、数据流分析、面向对
象设计、数据库设计、规格说明、测试计划、配置管理计
划、配置项变更控制、安装手册、培训手册、用户手册、
联机帮助、在线帮助、验收报告、项目总结等名目繁多的
技术文档，程序员实在是没兴趣也没动力做这种填单子、
爬格子、凑句子、费脑子的事情。有人说：写代码、调程
序是真刀真枪的‘战斗’，写了多少行代码就是占领了多少
新的阵地，排除了多少Bug 就是消灭了多少顽抗的敌人。
可写文档呢？写文档充其量是战斗之余的后勤工作，原本
就应该由电影里那些梳着小辫儿，打着快板儿的文工团美
眉们来负责。把程序员有限的生命浪费在无限漫长和无限
空虚的写文档过程里，不值呀！
真的不值吗？对这种事情，下结论时还是别太草率为
好。要知道，在技术领域里，任何一种偏激的，强调某某
问题一定如何如何的提法都会轻易被人用证据确凿的反例
驳倒。比如说，有人认为技术人员完全不必写文档，他们
的论据是，像微软这样的大型软件公司就雇有专职的文档
编撰人员。可据我所知，即便是在微软的项目组中，除了
用户手册、联机帮助等与最终用户相关的文档一般由专职
的用户体验（User Experience）人员负责编写外，其他的
技术文档，如规格说明书等还是要由程序经理和开发人员
亲自完成的①。此外，不同类型的项目对文档编撰人员的要
求也各不相同：同样是在微软公司，IE 浏览器的使用手册
当然可以由那些擅长商务写作而毫无开发经验的人来编
写，但像DirectX SDK 这类面向开发人员的产品，你能想
象得出，一个完全不懂编程的人该如何编写DirectX SDK
的用户手册吗？而且，并不是每家软件企业都有实力雇佣
足够数量的文档编撰人员，在国内为数众多的中、小型企
业中，因为项目投入有限，软件产品的大多数技术文档仍
然要由项目经理和程序员亲力亲为。
我不想在这里重复技术文档的重要性——直到今天还
认为文档可有可无的程序员只适合在1980 年代的中关村
里单打独斗——我只是想说，既然大家都知道技术文档的
重要，也都躲不开编写文档的差事，那么，与其天天说“怕”
写文档，还不如潜下心来，研究研究写好文档的法门。我
们都不是贾岛，也没必要像贾岛那样追求惊天地、泣鬼神
的名篇佳构。也许，只要掌握一些特定类型文档的编撰规
律和编撰方法，并在实践中不断体验写文档的乐趣，我们
对写文档的恐惧心理就早晚会烟消云散。
今天的案例和软件产品的用户手册有关。这里所说的
“用户手册”指的是所有面向最终用户，以印刷或电子方
式提供的，关于软件产品安装、配置与使用的技术文档。
通常，开发工具、开发包、程序库等产品的用户手册也被
称作程序员手册或开发指南，但它们和IE 等普通产品的用
户手册一样，都是面向最终用户的技术文档，也都在本文
的讨论对象之列。
不少开源软件的狂热爱好者认为，微软那些不开放源
代码的产品和开源软件相比，简直就是价高质次的“信息
垃圾”。我们姑且不论他们的说法是否正确，但只要对比一
下微软产品和开源产品的用户手册，大多数人就会自觉地
得出这样的结论：难怪微软的产品风行全球，难怪大多数
开源产品总也不能打动最终的消费者——这两类产品的用
户手册根本就不在同一个档次上嘛！的确，开源产品的文
档质量不高（这里说的是普遍现象，不排除某些特例的存
在）几乎已经成了业界的共识，可这究竟是为什么呢？别
着急，我们先来看两个实际的例子。
第一个例子是来自开源社区SourceForge 的LibBT 项
目。该项目的目标是为程序员提供一个支持BitTorrent 下
载（就是我们常说的“变态”下载）功能的程序库。我从
LibBT 的主页（http://sourceforge.net/projects/libbt）下载了
LibBT 1.0 版本。解压后，我发现在整个项目文件夹中，除
了源码和配置文件以外，可以算作用户手册或开发指南的
文档寥寥无几，充其量也就这么几个：
libbt-1.0\README：自述文件，描述了LibBT的功用和生成LibBT
库的方法。
libbt-1.0\docs\protocol.txt：BitTorrent 文件传输协议的
描述。
libbt-1.0\docs\protocol-ext.txt：BitTorrent 文件传输
协议的附加说明。
libbt-1.0\man\btcheck.1：例子程序btcheck 的用户手册。
libbt-1.0\man\btget.1：例子程序btget 的用户手册。
libbt-1.0\man\btlist.1：例子程序btlist 的用户手册。
现在，我们不妨做一个假设：如果某位程序员希望在
Linux 下编写一个图形界面的BitTorrent 程序，他也顺利找
到并下载了LibBT 的1.0 版，那么，仅凭上述这几份帮助
文档，他能够顺利完成开发工作吗？类似LibBT 这样的小
规模开源程序库还有许多许多，它们究竟该为程序员提供
什么样的技术文档呢？
第二个例子不是开发包，而是一个可供用户直接使用
的开源软件产品。为了防止阅读本文的程序员昏昏欲睡，
我特意选取了一个大多数Java 程序员都非常熟悉的软件
——著名的生成工具Ant。我下载的是Ant 1.6.1 版
（http://ant.apache.org/）。Ant 安装包内包含大量电子形式
的文档，既有自述文件和版本说明，也有用户手册和常见
问答（FAQ），仅用户手册就占据了22.9MB 的磁盘空间，
Ant 文档的齐备和详尽程度的确是开源项目中相当少有
的。为了方便大家分析讨论，我特地把Ant 1.6.1 用户手册
（Apache Ant User Manual）的目录结构翻译了出来，罗列
在下面：
Apache Ant 用户手册目录
概述
安装Ant
获得Ant
系统需求
安装Ant
生成Ant
库依赖性
平台相关问题
使用Ant
编写简单的Buildfile
项目
目标
任务
属性
内置属性
Buildfile样例
标记过滤器
类路径结构
命令行参数
引用
运行Ant
命令行
选项
库的目录
文件
环境变量
Java系统属性
Cygwin用户
OS/2用户
通过Java 运行Ant
Ant 任务
Ant任务概览
核心任务
..
可选任务
..
概念和类型
概念
..
核心类型
..
可选类型
..
命名空间
..
Antlib 文件
..
定制组件
..
监听器和日志器
与编辑器/开发环境的集成
基于Ant 的开发
..
Ant API 参考
..
许可协议
反馈和纠错
作者列表
怎么样，这份用户手册够详细的吧？和前面LibBT 的
例子相比，Ant 的用户手册已经具备相当高的质量了。不
过，我还是希望大家仔细想一想，在Ant 的用户手册中，
是不是也存在某些不尽如人意的地方呢？如果希望把Ant
的用户手册再提高一个层次，我们该从何处做起呢？
2 一些题外话
案例分析前，先说一个和写文档有关的趣闻。
许多程序员讨厌写文档，并由此讨厌和写文档相关的
一切工作，如讨厌记日记（Blog 除外）、讨厌读小说（武
侠小说除外）、讨厌查字典（金山词霸除外）等等，结果，
在软件开发领域里，语文水平不高的程序员大有人在。虽
然没人要求程序员必须会写四六骈文，必须会背《昭明文
选》，但最最起码的是，程序员总不能在技术文档中连篇累
牍地制造错别字吧。
比方说，上大学时，我有一次惊讶地发现，计算机系
某位师兄的毕业论文里赫然出现了“阀值”一词。我不解
其意，遍查权威工具书也一无所获。碍于面子，又不好向
那位师兄开口请教。毕业后，我多次听同事说起“阀值”
这个技术术语。万般无奈，我只好拉住一位好心的同事问
个究竟。谁知那位同事竟一脸诧异地说：“你在大学里是怎
么学的？课堂上老师没教过你吗？举个例子，假如考试成
绩60 分以上的算及格，60 分以下的算不及格，那这个60
分不就是一个‘阀值’吗？”
直到这时，我才恍然大悟，原来所谓的“阀值”就是
这么个东东呀。在我的经验里，位于临界点的数值叫“阈
值”而不叫“阀值”，这可以用工具书来佐证——《现代汉
语规范词典》中说：“阈：①门槛。②界限；范围。”很显
然，那些开口“阀值”、闭口“阀值”的人，是读了别字了。
可为什么会把“阈”错读为“阀”呢？是因为它们长得像
双胞胎兄弟，还是因为它们的五笔字型编码颇为近似？为
了查明真相，我重又回到学校里，专门花了几天时间旁听
计算机系的课程。苍天有眼，还真让我给碰上了：在一位
知名教授的课堂上，我亲耳听到该教授把“阈（yù）值”
读作“阀（fá）值”（由于众所周知的原因，我就不公开这
位教授的尊姓大名了）。现在我算是明白了，有这样的别字
师傅口传心授，这世界上怎么会少得了读别字、写别字的
程序员呢？
不留心的话，大家可能都不会察觉，这个“阀值”的
错误在技术领域竟是如此泛滥，不仅一些普通程序员“阀”
来“阀”去而浑不自知，许多严肃的教材、文献也义无反
顾地加入了别字工厂的行列。更为搞笑的事情还包括：在
Sybase 中文网站上的一篇名为“阀值管理”的文章，以及
3Com 中文网站上的一篇名为“RMON 和RMONⅡ：经济
有效的网络管理”的文章里，“阀值”和“阈值”两种写法
竟然同室操戈、互不相让；在金山词霸2003 专业版对
“Threshold”一词的完整注解内，除了包括若干个拼写正
确的“阈值”以外，居然也悄悄隐藏了一个刺眼的“阀
值”..
无论如何，这则有关“阈值”的趣闻都提醒我们，尽
管程序员们早在大学期间就已经彻底忘记了“语文”是门
什么样的功课，但一些有关语言文字的基本常识，我们还
是不要丢掉为好。此外，连小学生碰到疑难问题时都晓得
去请教字典，我们这些搞软件开发的可千万别被小学生们
笑话噢！
3 案例分析
正如软件必须满足用户的使用需求一样，技术文档也
必须满足用户的阅读需求。以这个标准来判断，本文案例
中给出的两种用户手册都不是最好的技术文档。
第一个例子——LibBT 文档的缺陷非常明显：LibBT
的用户手册不是质量好坏的问题，它根本就没有提供真正
意义上的用户手册！
从案例中提到的假设出发，如果某位程序员希望在
Linux 下编写一个图形界面的BitTorrent 程序，他也顺利找
到并下载了LibBT 的1.0 版，这时，他最想从LibBT 的文
档中获取什么信息呢？如果我是那位程序员，我最想知道
的是：LibBT 究竟是个什么东西？它实现了BitTorrent 的
哪些功能？它为我们提供的是动态库还是静态库？它的接
口类或接口函数有哪些？我们该如何在代码中嵌入
LibBT？如何将LibBT 与图形界面的应用程序结合起
来？..非常令人失望的是，除了自述文件（README）
中有几句无关痛痒的简介以外，我在LibBT 的发布包里就
再也找不到任何有用的信息了。LibBT 的man 文件夹下是
用LibBT 库开发的三个示例程序的命令行语法说明，但我
想编写的是一个图形界面的BitTorrent 程序，学习这些命
令行参数又有什么用呢？docs 文件夹看上去存储了最有价
值的文档，可里面能找到的只有两份描述BitTorrent 传输
协议的文件——天哪，我下载LibBT 的目的就是想在不关
心BitTorrent 传输协议细节的情况下，直接使用第三方的
开发包来实现BitTorrent 程序， 现在你又让我阅读
BitTorrent 传输协议的描述文档，这不是在嘲笑我舍本逐末
吗？
实际上，很多程序员在编写技术文档时都喜欢像
LibBT 的作者那样一味卖弄技术，而不考虑最终用户的实
际需求。这种现象在许多以开发包形式发布的软件产品中
尤其明显：为开发包写文档的程序员总是习惯性地认为，
开发包本来就是提供给技术人员使用的，使用者应当了解
开发包的实现细节，甚至需要仔细研读代码，所以，像“手
册”、“入门”或“指南”之类小儿科的文档根本没有必要
存在。这种想法之所以错误，就是因为它忽视了一个重要
的事实：编写开发包的人和使用开发包的人往往有不同的
利益关注点，他们对技术文档的需求也大相径庭。拿LibBT
的例子来说，编写LibBT 的人关注的是BitTorrent 协议的
细节，而使用LibBT 的人关注的就是LibBT 的接口和使用
方法了。仅把BitTorrent 协议说明提供给用户，这种做法
和仅向电视机的购买者提供一份电路图没什么区别。
我还见过某些类库的开发者在编写用户手册时，只是
把所有类、属性、方法的说明按字母顺序排列在一起，除
此以外不提供任何资料。要知道，使用类库的程序员最关
心的是如何将类库中的类、属性和方法组织成一个有机的
整体，以解决实际问题。对于类库来说，字典式的参考固
然重要，可缺少了入门性的引导和帮助，程序员该如何了
解基于类库编程的具体方法和步骤呢？当然，在开源领域，
聪明的程序员也可以通过阅读源码获得足够的知识，但假
如竞争对手的产品借助出色的文档免去了用户钻研代码的
苦恼，那些文档不健全的产品还能在市场上立足吗？
相比之下，Ant 的文档就比LibBT 的文档好了许多倍。
最明显的一点是，Ant 用户手册的结构严格遵循了一条文
档编撰领域里的终极定理——我把这条定理称为编撰用户
手册的“三段论定理”，即：
好的用户手册必须包括三大部分：概述、指南和参考。
千万别小看这条简单得不能再简单的“三段论定理”。
仔细观察就不难发现，几乎所有优秀的用户手册都符合这
一定理的要求。
拿Ant 用户手册来说，最开头的“概述”一章解决了
“Ant 是什么”和“为什么要用Ant”这两个初识Ant 的程
序员最关心的问题。所以，别看概述部分的篇幅不长，它
在用户手册中的作用和地位却着实了得。试想一下，那些
刚刚购买和下载软件的用户大都对新的软件缺乏认识，如
果我们能用一两页通俗易懂的文字明明白白地告知用户，
产品可以帮助他们解决什么问题，大多数用户就会摩拳擦
掌，跃跃欲试了。需要说明的是，在英文用户手册中，像
“Introduction”、“Overview”、“What’s ...”、“Getting Started”
之类的章节，都能对应于“三段论定理”中的概述部分。
“三段论定理”中的指南部分一般可以对应于英文用
户手册中的“Tutorial”、“Guide”、“Manual”、“How to ...”、
“Using ...”等章节，有时也包括“Getting Started”或“Step
by step”等内容。简单地说，指南就是手把手地教用户如
何使用软件产品，如何完成特定的任务，它解决的是“如
何做某事”的问题。在Ant 用户手册中，“安装Ant”、“使
用Ant”、“运行Ant”这三个章节就明显属于指南的性质。
通过对这三个章节的阅读，一个从未用过Ant 的人至少可
以安装和运行Ant，并管理简单的项目了。
“三段论定理”中所说参考指的是，任何出色的用户
手册都应当提供完整齐备、组织合理、便于查询的参考资
料，这和任何优秀的技术类图书都应在书后提供参考文献
或交叉索引的道理一样。参考部分在英文用户手册中的对
应章节包括“Reference”、“Glossary”、“Index”等等，它
们要解决的是“如何快速查找特定信息”的问题。在Ant
用户手册中，“Ant 任务”、“概念和类型”、“Ant API 参考”
等几个章节都可以起到参考的作用。例如，当我看到别人
写的某个Buildfile 中有了一个我从未用过的“CvsTagDiff”
任务，我可以通过“Ant 任务”这一章中按字母顺序排列
的任务名列表，快速查到“CvsTagDiff”，并了解该任务的
具体用途。除了Ant 这样面向开发者的软件产品以外，绝
大多数面向普通消费者的软件也需要在用户手册中提供足
够的参考内容。例如，像Word 这样的文档编辑软件，其
印刷手册或联机帮助中如果没有快捷键、工具栏按钮和菜
单项的速查，最终用户就多半要叫苦不迭了。
为什么一份好的用户手册必须符合“三段论定理”的
要求呢？这是因为，用户手册应尽可能地满足不同类型用
户的使用需求，而“三段论定理”中的概述、指南和参考
三要素正好互为因果，相辅相成，构建了一个循序渐进的
文档体系：对软件产品一无所知的用户首先借助概述部分
了解产品的基本特性；然后，用户可以在指南的帮助下，
由浅入深地学习产品的使用方法；接下来，用户一旦在使
用过程中遇到疑难，产品的参考资料就可以发挥答疑解惑
的作用了。
在微软公司大多数产品的用户手册中，我们都能找到
符合“三段论定理”的文档结构。以我们程序员最熟悉的
MSDN 文档（我们可以把MSDN 文档视为微软所有开发
工具和开发包的用户手册）为例，MSDN 文档在结构和内
容方面的规范性非常明显，在它的目录结构中，几乎每一
个技术单元都是由“Overview”、“Tutorial”、“Reference”
或类似的文档要素组成，整个MSDN 文档库组织有序、编
排合理。应当说，微软公司在技术文档编撰方面积累下来
的许多经验、方法都非常值得我们学习和借鉴。
现在，我们已经知道，案例中给出的Ant 用户手册在
结构上符合“三段论定理”的要求，其质量和LibBT 的文
档质量相比，有天壤之别。但我为什么还要说Ant 用户手
册也不是最好的技术文档呢？
如果用更严格的标准来衡量Ant 用户手册的质量，我
们还是能发现其中的许多不足之处。其实，评估一份用户
手册的方法和评估一套软件的方法没有多大的不同。回想
一下，当我们考察一个软件产品的质量时，最关键的标准
是什么？没错，是该产品是否符合用户的需求。熟悉面向
对象软件工程和用例驱动开发的程序员都会想到，我们可
以根据需求分析阶段得到的用例模型，依次评估软件产品
在每个用例实现（Use Case Realization）或每个情境
（Scenario）中的表现，以判断软件产品与用户需求之间的
吻合程度，并综合衡量软件产品的质量。那么，我们是不
是也可以通过用例分析和用例验证的方法评估技术文档，
特别是用户手册的质量呢？
在此前的分析中，我们已经不自觉地使用了用例分析
的方法。例如，“三段论定理”中的三要素分别对应了三种
用户需求——了解产品概况、熟悉使用方法和查考疑难问
题，它们不就是最终用户在阅读用户手册时的三种主要用
例吗？根据我们的分析，Ant 用户手册可以基本解决这三
种主要用例涉及的需求问题，但这种“解决”是不是最完
整、最高效的解决方案呢？也许，我们还需要设计更深层
次的用例，以寻找这一问题的答案。
举个例子，Ant 用户手册中的“使用Ant”一章属于指
南性质，按照“三段论定理”的要求，该章节的作用是指
导用户学习Ant 的使用方法。那么，“使用Ant”一章是否
能涵盖Ant 的大多数常见用法呢？答案是否定的。“使用
Ant”一章仅仅介绍了Ant 的基本用法，并给出一个最简单
的Buildfile 样例，这充其量能告诉用户如何用Ant 完成最
基本的软件生成任务，它无法提供更多的指导性信息。例
如，“使用Ant”一章给出的Buildfile 样例包含了一个名为
“clean”的任务，但该文档却没有展开论述，类似“clean”
这样的清理任务在Ant 中应该如何实现，其中可能涉及哪
些Ant 任务、属性和类型——这说明，Ant 的用户手册无
法实现这一具体的深层用例。此外，对于“如何集成不同
的Ant 项目”、“如何用Ant 管理文件夹和文件结构”、“如
何记录和显示错误信息”、“如何在Ant 中访问CVS 源码
库”、“如何压缩和解压缩归档文件”等在Ant 的使用过程
中颇为常见的问题，“使用Ant”一章都没有给出详细的介
绍。有人说，程序员可以自己从Ant 用户手册中的“Ant
任务”一章中查找到相关的内容，也有人说，Ant 提供的
常见问答（FAQ）也包含类似的信息。但不要忘了，不同
类型的文档肩负的职责不同，适合的用例范围也各不相同。
“使用Ant”一章是指南型文档，适用于“学习Ant 使用
方法”这一主要用例，而“Ant 任务”一章以及常见问答
（FAQ）都属于参考性质，其结构和内容都只适用于“用
户遇到问题时快速查考”的主要用例。换句话说，Ant 用
户手册中的指南部分缺少对“学习通过Ant 集成不同项目
的方法”等深层用例的实现，没有完全承担起引导、教授
的职责。那些没办法在指南部分掌握足够技能的用户只有
到参考部分碰碰运气，可依靠参考或索引来学习软件用法
就像只凭着一本英汉字典学习英文一样，都是吃力不讨好
的事情。也就是说，在类似的情况下，我们应尽量补全指
南文档以实现所有深层用例，而不是像踢皮球一样把无辜
的用户踢到其他并不适用的文档类型那里。
关于用户手册的指南部分，微软MSDN 文档中的大多
数相关章节都给我们提供了最好的范例。比如说，在“使
用.NET 框架编程”②一章里，就包含有“使用ADO.NET
访问数据”、“使用.NET 远程机制访问其他应用域中的对
象”、“访问Internet”等30 多个主题，几乎涵盖了.NET 开
发中的所有常见任务。显然，用户可以在这些主题教程的
引导下，循序渐进地学习.NET 环境下的开发方法，了
解.NET 编程的具体步骤。最重要的是，MSDN 文档中几
乎所有指南内容都是以主题方式组织起来的，每个主题都
试图解决一个用户最关心的问题，或试图指导用户完成一
个具体的任务。从这个角度看，我们也可以把MSDN 中的
指南型文档称为“面向主题的文档”或“面向任务的文档”。
Ant 用户手册中的参考部分也乏善可陈。最让人郁闷
的是，Ant 用户手册在“Ant 任务”一章中将Ant 任务分别
罗列在“核心任务”和“可选任务”两大类中，在“概念
和类型”一章也有类似的做法。虽然每一个类目下的条目
是按字母顺序排列的，但Ant 用户手册就是没有给出一个
包含所有Ant 任务、属性和类型的完整列表。用一个简单
的用例就可以难倒Ant 的用户手册：假如我在别人编写的
Buildfile 中发现了一个我从未见过的“JJTree”标签，并想
在用户手册中查找它的含义，可我怎么知道这个“JJTree”
是一个Ant 任务，还是一个Ant 类型呢？就算我能确定
“JJTree”是Ant 任务，那我是该到“核心任务”里查找，
还是该到“可选任务”里查找呢？Ant 文档缺乏统一索引
的弊病显然影响了用户的查询效率；为了提高效率，我自
己就经常使用grep 检索Ant 文档——可不要小看这个问
题，也许，检索效率上的些许差别就足以促使你的潜在用
户选择竞争对手的产品呢！
在参考和索引方面，微软的MSDN 文档表现得同样无
可挑剔。除了组织完善的“Reference”、“Glossary”等信
息内容外，MSDN 还为我们提供了统一的索引（Index）、
查找（Search）和收藏（Favorites）功能。在这些功能的帮
助下，程序员几乎可以毫不费力地在庞大的MSDN 信息海
洋中自由穿梭。此外，在MSDN 的每个文档页面中，以相
关主题（Related Topics）、参见（See Also）、超级链接
（Hyperlink）等形式出现的交叉索引机制也屡见不鲜。无
疑，在文档检索功能的完善和易用方面，微软早已遥遥领
先，像Ant 这样的开源项目是难以望其项背的。
留心电子文档技术发展的程序员可能已经注意到了，
微软在技术文档编制方面的出色表现和微软在相关技术领
域内的积累密不可分。仅仅在电子版的帮助文件格式上，
微软就先后推出了*.HLP、*.CHM 和*.HxS 等三种版本。
据说，在未来的Longhorn 操作系统中，帮助文件的性能还
会有质的飞跃③。当然，技术并不能决定一切。像Sun 的
JavaHelp （ http://java.sun.com/products/javahelp/ ）、Oracle
的Help for Java（http://otn.oracle.com/tech/java/help/）等跨
平台的电子文档生成工具也可以提供较丰富的功能特性，
但使用这些工具发布的优秀文档仍然少之又少。也许，微
软在文档领域的成功更多地是源自该公司重视用户需求、
强调产品易用性的一贯思路吧。
4 补充说明
自从“面向对象”一词在业界广为流传以来，程序员
们似乎都对“面向..”的说法情有独钟，以至于“面向
方面”、“面向契约”、“面向接口”、“面向用例”、“面向模
式”、“面向架构”、“面向组件”等术语甚嚣尘上，一发而
不可收拾。在这里，我也赶一回时髦，用“面向..”的
构词方法，简单列举些普通用户常见的技术文档类型：
.. 面向天才的文档：编写只有少数专家才能看懂的文
档。此方法只适用于科学研究等少数场合，绝不适用
于用户手册等为最终用户服务的文档。
.. 面向白痴的文档：绝大多数用户手册中的概述和指南
部分都应该是面向白痴的文档，只有这样，文档的易
用性才能得到最好的体现。
.. 面向概念的文档：以阐述基本概念为己任的文档，前
面“三段论定理”中所说的概述型文档，以及常见的
自述（README）文件都属于这一类型。
.. 面向任务的文档：指南型文档的最高表现形式，着重
描述任务的执行方式，而非具体的技术细节。MSDN
中比较常见的“How to ...”章节就是这一类文档的优
秀范例。
.. 面向检索的文档：参考、索引、术语表以及所有电子
形式的文档都可用于信息检索，但不同的编撰方式对
检索效率的影响极大——这需要文档编撰者拥有更
多的信息检索知识和更好的文档编撰工具。
.. 面向问题的文档——常见问答（FAQ）是一种开源领
域常见的，形式灵活，效果也相当不错的参考资料，
但大多数FAQ 的共同缺点是组织结构松散，缺乏有
效的索引和分类体系。
.. 面向错误的文档——主要包括疑难解答、错误列表、
故障速查等文档。
.. 面向法律的文档——最终用户许可协议（EULA）、软
件许可方式声明（LICENSE）或其他法律文档往往也
是软件产品的重要组成部分。
.. 面向历史的文档— — 包括版本历史（ Release
History），大事年表（Timeline）等等。
.. ..
5 总结一下
.. 写文档也有一定的规律可循，程序员千万不要“怕”
写文档；
.. 技术文档或为开发者服务，或为最终用户服务；认真
把握文档使用者的需求才是写好文档的捷径。
① Microsoft. MSF Team Model.
http://www.microsoft.com/msf/, 2003
② Microsoft. Programming with the .NET Framework.
http://msdn.microsoft.com/library/en-us/cpguide/html/cpconP
rogrammingWithNETFramework.asp, 2004
③ Microsoft. Introducing Windows "Longhorn" Help.
http://msdn.microsoft.com/library/en-us/htmlhelp/html/hwms
cIntroducingWindowsLonghornHelp.asp, 2004
本文地址：http://com.8s8s.com/it/it24828.htm