2011年技术文档写作年终总结系列之四：内容组织技巧

最后更新于： 2023年2月18日

前面已经陆续写了三篇技术文档写作总结系列了（1, 2, 3），貌似还没专门从用户手册的写作内容方面进行总结。本文就谈谈一些内容组织技巧吧。

一般来讲，高质量的用户手册，其内容组织在整体上要依赖于良好的目录结构层次布局。只要目录结构清晰，逻辑性强，就容易展开来写。下面是我在实际撰写用户手册中常用的模式：

1. 区分简单情形与复杂情形

某些功能有多种操作方式，其中一些相对简单，另一些则较为复杂，适合不同需求的用户进行选择。这种情形下，最好就是明确地将简单和复杂的情形分开介绍，不同层次的用户各取所需。值得注意的是，很多时候，复杂情形是在简单情形的基础上通过添加若干操作来实现的。因此，我们可以在介绍简单应用情形时详细描述每个细节，而在介绍复杂应用情形时，提示读者可以参考前者的基本设置，然后只介绍关键步骤。

举例：如何将邮件发给收件人？

简单情形：直接发送给一个收件人
复杂情形：批量发送或者定时发送

2. 并列型功能介绍
如果实现同一个功能的几种操作方式没有重要性或者难度上的区别，可以将它们放在同一个层次的目录下。

举例：发送邮件的方式有哪些？

a）通过web界面发送；
b）通过客户端发送；

3. 按照逻辑顺序来介绍

实例：

设置系统规则、准备基础数据 — 实际操作 — 数据归纳总结或查看 –补充说明

4. 按软件界面来介绍

对于逻辑性不是特别强，功能也不算很复杂的模块，可以直接按照软件界面来介绍。这种介绍方式的优点是比较直观。

5. 按功能主题来介绍

很多时候，一个复杂功能的实现要依赖于分散在系统各个模块的子功能。这个时侯就不适合按照软件界面来分开介绍了，不然用户为了学习这个功能，需要在用户手册中翻来翻去的，非常麻烦。此时，我们最好是建立一个主题，然后展开目录结构，将所有关联的子功能包进来介绍。当然了，对于那些本身被很多模块关联的子功能，不一定非要将其放在某个主题下，你可以将其放置于目录结构中相对独立的位置，然后链接到各个关联的章节。

6. 将公共功能模块独立出来

有些用户手册的内容十分之庞大（例如大型的企业管理软件），不太适合只用一本书来介绍，而是分成几本书，每本书侧重于一个大的功能模块。这些书之间既相对独立，又有部分关联。在这种情形下，单独将公共功能模块部分集中在一本书中就十分有必要了，可以将之定位成“基础知识”或者“入门指南”。其他模块涉及到公共功能的话，直接给出链接，让读者参考公共功能模块所在的用户手册，而不必在具体的应用情形中反复描述这些基础知识。实际的应用情形其实比这里介绍的要复杂多了，以后有空我会继续展开来写。

除了讲究目录结构之外，链接也是个很值得研究的话题。Html格式文档的好处之一就是强大的链接功能，可以交叉引用。PDF当然也可以有内部链接，不过如果你的用户手册很庞大，需要分成几本书来介绍，那么跨书引用就不是很方便了，这个缺陷是无法避免的。适当的放置交叉引用链接，有助于更好地引导读者去理解用户手册。

至于具体到某个功能细节的描述，通常的做法是三段论：是什么、为什么、怎么做。首先简短描述这个功能是为了实现什么目的，其次可以介绍这种设计的理由（也可以说是好处等，但这一步其实不一定要写出来），最后详细写出如何操作。语言风格应当是平实，准确，不能花哨，且尽量避免过于高深的术语。