原文链接：http://bbs.giltworld.com/dispbbs.asp?BoardID=46&ID=4795

5．  根据前提条件、后继要求以及相关任务，编写其它任务

你可以按照前面介绍的方法去写其它的任务。还不熟悉的话，就重新看一边2～4的内容吧。

这时，估计你就会有一个疑问，一个设备的操作过程很多，难道从5个任务就能够覆盖到所有的操作指导？

我的答案是肯定的。你只要完成了一个任务操作的指导，从这个操作指导的各个部分（包括目的、前提条件、过程相关信息等等）的内容中，我们可以发散地找出很多的线索。根据这些线索，我们可以写出这些任务或者描述。再根据这些任务和描述，有可以发散出更多的线索。这样循环下去，基本上就能覆盖。

如何收敛？呵呵，不用考虑收敛的问题。因为你的产品的功能就这么多，不要担心。

6．  补充需要的描述和参考

现在，你的任务已经写得差不多了，下面你应该去补充需要得描述和参考信息。

记住，对于产品的技术文档来说，描述通常指讨论那些与你讨论的任务有关的事情。而参考信息呢，则应该尽可能覆盖所有的信息。

技术文档中的描述，从所描述的对象看，一般可以分为3类：

从描述的对象看，Concept有以下3种分类：

• 对系统、硬件、软件、用户文档本身外观、结构、组成、属性等特性的描述
• 对功能（feature）和功能实现方式、运行原理的描述
• 对任务的描述。

而从描述的方法来看，一般有6种类型：

• 技术描述－从颜色、重量、尺寸、形状、数量、材质、温湿度等能够客观测量和量化的参数进行的技术描述。
• 扩展定义－用于解释一个复杂的技术术语，这些术语对任务的执行起到重要的作用。描述包括解释、应用、举例。
• 分类－将复杂的对象分解成简单对象进行描述，可以将一组对象划分成不同类别，或者将一个对象归到某一组读者已知的类别中。
• 比较－将两个或者两个以上的对象进行类比的描述方法。
• 过程描述－对一个对象按照时间顺序或者自然的发展顺序进行描述。
• 因果关系－描述为什么一个事物会发展到当前的状态的原因，或者是一个事务将发展都某个预期状态的现状。

参考信息用于说明任务所需要的信息和数据支撑。通常用于描述一个产品的有规律的特征，如：编程语言中的命令。

这类主题的特征是内容及其描写方法有很强的规律性，如食谱、文献列表、命令。参考型主题能让读者快速找到依据。

产品的技术文档中，参考信息通常是：

• 输入信息，如人机命令、人机界面窗口、编程语言的命令
• 接口信息，如接口函数、协议参数
• 输出信息，如告警信息、打印信息、函数返回值
• 文献列表

7．  重新组织你的文档的结构

目前为止，你已经基本完了所有的操作任务指导、产品的各种描述以及各种参考信息。接着，你就可以组织你的文档的结构，也就是如何顺序安排你写的各段的信息（我们统一称为主题）

技术文档的组织结构要求与你的读者的阅读习惯和阅读的目的有着相当大的关系。

这里，我们简单地根据读者的阅读目的分为学习和接受指导。

如果你的读者阅读的目的是学习。那么你应该运行原理描述→操作说明→操作任务指导→参考信息的顺序安排

如果你的读者的阅读目的是接受指导，那么，你应该按照操作任务指导→操作说明→运行原理描述→参考信息的顺序安排

其中，

操作说明是对操作任务指导的解释，

参考信息是对操作中用到的信息的说明，如命令格式说明、回显信息格式说明等。

还有就是性能参数等。从理论上这些描述也应该是一种参考信息，不过可能描述的方式不太一样。

遗憾的是，一般读者阅读技术文档的目的，大多都是接受指导。即使兼顾着学习的目的，但多半也是边操作边学习，很少有时间去完整阅读你的技术文档。所以，基本上你按照这个目的去构建你的文档结构是没有太大问题的。

那么我们就按照这个目的讨论一下怎么组织你的技术文档。

方式一

方式1适用于较小的产品。这种产品通常所具有的功能和特性较少，对于一个读者来说，一本文档足以讨论清楚。

第一部分一般是留给安全说明的。这个先放一放，后面我们会谈到。

第二部分是操作任务指导。

操作任务指导通常会有很多的内容。这时，你应该注意，先把一个或者一群特定用户（读者）所涉及的任务放到一本书中，而另一个或者一群特定用户（读者）所涉及的任务放到另一本书中。分配的时候，不要怕重复，用户A和用户B很可能会执行同一个任务。

对于某一个特定用户的文档，你开始安排操作任务指导的顺序了。我建议的顺序是按照安装配置管理→安全管理→性能管理→产出物管理→故障管理的顺序进行。这些内容我们在前面列举5个用户任务的时候已经说明了。

第三部分是操作说明。顺仿照第二部分就可以了。

第四部分是运行原理。

运行原理的安排顺序是按照：

高端流程→低端流程、各低端流程按照时间顺序

总体→局部、各局部按照顺时针方向或者由外到里的顺序

第五部分是设备描述

附录一部分是安装和操作中的图表

如果安装和操作中使用可较大的图表，如安装示意图，那么，这些图表放在正文中会影响阅读的兴趣和连贯性。这些图表放在附录中是一个很好的选择。

附录二部分是参考信息。

设备描述一般采用描述的方式，

方式二

方式2适用于功能较多的产品，通常对于一个读者，一本文档是不足以描述清楚的。

方式2是按照某一个（群）读者所面对的产品的不同的功能（面向用户所体现的功能）来进行分册。

第一章 概述和范围，可以包括安全说明

第二章 功能（feature）包描述和功能描述。 请注意，这里的功能是只面向用户能够体现出来的功能，或者叫做特征。

第三章 软硬件配置。说明针对不同的功能应用的不同配置要求。

第四章 功能交互和限制（如果有的话），说明该功能是否会影响到其它功能，或者受其它功能的影响，如前驱对漂移的影响。同时也可以说明该功能是否会收到环境、人力、工具等其它方面的限制。如描述内存对该功能实现或者能力的影响。

第五章 数据输入（如果需要的话），说明为实现该功能，需要准备和进行的数据配置。

第六章 用户－系统接口描述（如果有的话）。

第七章 安装，包括软硬件的安装。

第八章 功能的操作，说明改功能需要进行的各种操作，或者改功能的应用操作。

第九章 维护，说明改功能和功能包的维护。

附录一部分是安装和操作中的图表

如果安装和操作中使用可较大的图表，如安装示意图，那么，这些图表放在正文中会影响阅读的兴趣和连贯性。这些图表放在附录中是一个很好的选择。

附录二部分是参考信息。仅包含与本文档有关的操作信息。

在需要多本技术文档的情况下，可以按照方式1的做法，此时，不同的部分（章节）独立为不同的书。也可以就是按照方式2进行。但是最好的是方式1和方式2并行，以便更好的适应读者的习惯。

8．  修改你的语言和文字

现在你的文档已经基本上成型了，接着的工作就是开始修饰一下你的文档。

下面介绍一些修改的原则，如果你相对熟悉一些，你可以一次性按照这些原则进行修改，如果你不是很熟悉，那么建议你一次只关注一个原则。

原则1－根据用户需要，去增删改你所表达的信息。

文档信息建立基础是用户需要，你应该只描述任务实现过程中必要的信息，多余的信息对任务实现没有意义。

常见的多余的信息多会发生在图上。技术文档的作者都会听说“文不如表、表不如图”。因此都习惯于用图表来说明。但多余的信息也通常会发生在图表上。

举例：

1 在IE地址栏输入网址bbs.giltworld.com ，如下图。

这个图实际上没有任何意义，因此不需要插入任何图。

一般来说，图，特别是界面图，往往带有很多的与你所描写的主题无关的内容。如上图中，窗口标题实际上只是在你输入网址后才出现。这就可能让读者产生误解。对于这个例子来说，即使你需要图，也把这个图只截出地址栏一块。 

原则2－改变你所描述内容的知识水平

我们一直在说，文档信息建立基础是用户需要。同样，你所描述内容的知识水平也应该与目标读者一致。你的目标写给谁看的，谁就是你的目标读者。

在上面的例子中，这种写法，是针对网络新手的。如果你的目标对象是老手，那么他们就会觉得你的文档不实用，会失去阅读的耐心。这时你就必须改变一下你的描述。

例子

对于老网民来说，你只要告诉他网址他们就知道了。

论坛的域名是bbs.giltworld.com，输入用户名和密码后，你就能发贴和回复，否则你只能按照游客的身份浏览网站概况。 

原则3－考虑是否需要增加例子

技术写作中有一句俗话“与其化精力写好文档，不如化精力写好例子”。因此，你至少应该考虑是否需要增加例子。

例子的用法有两种，一种是在过程描述的一个步骤中增加例子。另一种是对整个任务的过程举一个例子。

举例

2 在用户登录区域框中输入用户名和密码。

用户名和密码是在您注册输入的。如果您忘记了密码，请单击＜忘记密码＞

这段，我们可以考虑举一个例子，改写如下：

2 在用户登录区域框中输入用户名和密码。

如，你可以输入用户名和密码如下图

用户名和密码是在您注册时输入的。如果您忘记了密码，请单击＜忘记密码＞

值得提醒的是，不要让你的例子代替你的操作指导。

虽然例子很重要，但是例子从根本上还是操作指导的补充，目的是为了让读者更好地理解操作指导。所以，你应该的写作过程是先写操作指导，再补充例子。 

原则4－让你的段落只有一个主题，并且主题句应该在段落的第一句。

检查一下你的文字吧。对于技术文档而言，你的段落应该只有一个主题，而且主题句应该在段落的第一句。

这个比较好理解，就不多说了。常见的应该注意的情况有3种：

第一句不要用问句。问句虽然可能激起读者的兴趣，但不是主题句。在技术文档中不合适。

第一句不要用“本节说的是”、“上文说到”之类的开场。这种情况很容易造成指代不明确。

第一句如果是“应该注意的情况有几种”，那么把这个“几”字改为数字“3” 

原则5－让所有句子的长度，保持在一个范围内。

句子越长，那么阅读和理解的难度就越大。但是如果句子太短，那么阅读起来就感觉很生硬，逼近人类的语言不是计算机语言。

句子的长度，与阅读的难度有关。而同样长度的句子，不同知识水平的人理解的难度也不同。这是一个比较复杂的“函数”。不过，做为新手上路，我想你可以先设立一个句子长度的上限。

一般的句子，不要超过56个字（在大约1行半），如果是过程描述中的“动作命令”，不要超过50个字。

如果你写的是英文，那么一个句子不要超过25个单词，而过程描述中command，则不要超过23个单词。

就按照这个上限吧。如果超出了，就改写你的句子。 

原则6－关注列表的编号和方式

列表（list，word中称为项目）分两种，一种是有编号的如1、2、3 ，或者A、B、C；另一种是无编号的，，如l 、※。

你应该这两种列表的用法全文一致。两种列表的使用原则介绍如下：

1）  如果是有一定顺序的，用有编号的列表；

2）  如果是没有顺序关系但数量多于7条，则用有编号的列表；

3）  如果是没有顺序关系但其中某些条目会被其它文字引用，则用有编号的列表；

4） 如果列表下一级还会出现列表，那么这一级列表要有编号；

5）  如果是没有顺序关系的，并且不符合2）3）4）的，则用无编号的。

编号的列表的层次不要乱了。 

关于修改的原则（包括写作的原则）还有很多。不过，刚刚开始写作，我认为还是先关注这6个内容吧。 

9．  编写前言和概述

前言和概述都是介绍文档内容。前言介绍全文的内容，主要是介绍全文的用途，类似与全文的目的。概述是介绍一个章节的内容。

写前言和概述，一般注意以下内容：

原则1－如果你的文档中的章（第一级标题）的数量超过3个，那么你就应该有一个前言。如果你每一章的内容超过3个节（二级标题），那么这一章就应该有一个概述。依此类推。

例如：

一个文档的正文结构可能是这样的

前言

第一章 安全说明

第二章 界面使用说明

2．1节 概述

2．2节 界面区域说明

2．3节 菜单的使用说明

2．4节 快捷按钮使用说明

2．4节 键盘使用说明

2．5节 鼠标使用说明

第三章 安装操作指导

3．1节 概述

3．2节 安装指导

3．3节 连接配置操作

3．3．1节 简述

3．3．2节 注册用户

3．3．3节 登录论坛

3．3．4节 重新获取密码

3．3．5节 登出论坛

3．3．6节 注销用户

3．4节 发表新话题

3．5节 发贴量管理

3．6节 常见故障处理

第四章 论坛性能参数

第五章 联系我们
 

原则2－前言和概述之说明本书或者本章节的所描述的内容。不要谈其它的。

一个常见的不恰当的方式是在概述里讨论与后面内容有关的概念、或者规则。这种方式我不认为是错误的，但是不赞成。

读者不一定去读你的概述，而很可能跳过去读你的其它章节。 

10．编写安全事项、设置目录和索引

安全第一，这就不用多说了。安全提示请先关注2点：

• 全文中的某个操作如有可能造成对人身和设备的损坏，那么，在全文的最前面应有独立部分的提示，并且
• 在该操作前或者操作步骤中应有安全提示，并且
• 操作步骤中的安全提示应与操作步骤在同一页。

目录一般放在正文的最前面，并且最好是显示3级标题。

索引放在附录和术语表的后面，当然放在目录的后面正文的前面也是可行的。

索引一定是名词，使用动词、形容词、副词没有太大的用途。索引可以是动宾词组。如果使用动宾词组，一定是先名词后动宾词组。

如：

网段                     4、5、6

网页                     7、9、34

       登录网页       9

       浏览网页       34       

网址                     5、6、9、34

好了，到现在为止，你已经基本完成了一个手册的初稿了。以后你可以交给子系统专家去做审核、交给文档专家审核、交给测试人员去测试、交给某个客户去验证，等等。再经过修改。恭喜你，你已经完成了一个技术文档了。