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

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

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

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

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

举例:如何将邮件发给收件人?

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

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

举例:发送邮件的方式有哪些?

a)通过web界面发送;
b)通过客户端发送;

3. 按照逻辑顺序来介绍

实例:

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

4. 按软件界面来介绍

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

5. 按功能主题来介绍

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

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

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

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

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

“2011年技术文档写作年终总结系列之四:内容组织技巧”的6个回复

  1. 非常好的年终总结。赞!

    “至于具体到某个功能细节的描述,通常的做法是三段论:是什么、为什么、怎么做。”我一般是先写为什么:用户为什么要用这个功能?我们为什么要为用户提供这个功能?这个功能可以帮用户解决什么问题?然后再写是什么:目前我们提供了哪些具体功能。最后写怎么做。

  2. 总结得很好,还是挺有想法滴。“按功能主题”其实就是传说中的“基于任务/场景”写作,当然,必要的参考性信息(诸如“界面参考”之类)可以单独提供,作必要的链接链过去即可。

    1. 国外比较推崇的是类似DITA这类基于话题的写作工具,不过我还没试过这玩意。其实工具也只是一个手段,内容组织方式才是核心,要让用户更容易地找到想要的内容。

      1. DITA只是方法,基于DITA的开发工具诸如Arbortext Editor。不过还需要一系列配套的大纲设计、内容发布工具和平台的配合,只有大公司买得起,用得起^_^

        1. 是呀,单纯用那个开源的DITA Open Toolkit还有相当多的配置要做,一般人玩不起。商业解决方案估计比较容易上手,小公司呢买不起,也用不到这些牛刀啦~我现在用的是Sphinx reStructuredText,对付小型文档绰绰有余。

发表回复

您的电子邮箱地址不会被公开。 必填项已用*标注