用户手册开发（二）-组织文档

提纲

      我们有时候会怀疑：写提纲一定那么重要吗？如果将文档工作类比于软件开发，这个答案就非常明显了。在软件开发当中，设计是编码的必要前奏，在你没有五六年的工作经验之前，没有设计的编码将会是一塌糊涂。同样，没有提纲的文章，也会是乱七八糟。

      提纲让我们能做好内容规划和章节划分。写提纲是一个文章整体的构思过程，能让我们掌控整个文章的大局，做好了大局的工作，章节的内容，在提纲的指导下，很容易节节击破。好的提纲，能让文章大方向的改动变得最小，减少开发人员的工作量，否则出现了大方向的改动，内容也需要跟着变动，工作量也会随之增加。

      提纲让我们理清文章的整体思路。文章很重要，思路更重要。网上的模板很无聊，它只是显示了一堆骷髅。打开百度页面，搜“用户手册”，看了一些模板就想吐血，因为它们只实际上只说明了一些注意事项，面对你自己文档开发的实情，你仍无法动笔。在模板无效的情况下，自己动笔写提纲，才能解决问题。写提纲时，会驱使我们思考：我们要达到什么目的，我要写什么，我该怎么写。我认为这样思考的结果便是思路。

      我不是语言学家，直接定义“什么是好的提纲”是一项艰苦卓绝的挑战。但要提到不好的提纲或者没有做好提纲的文章，你也许会有很多共鸣。下面列出了几个反例：

（1）结构倒置。

      先看看下图的提纲有什么问题？

 

图1

      如果你在看书的不经意间，翻到了最后几页，你经常会看到后面几页的附录，上面一般写的就是××表，××解释，××比较等等。上面的提纲将这些应该属于附录的名词解释，字符集对照表放在了前几页，是非常明显的结构导致的现象。

（2）内容与标题偏离。

      面对高考800字的作文和四六级150字的作文，你还记得论据一定要围绕论点展开这句话吗？同样，内容也要如众星般捧着标题-这颗月亮。为什么会存在内容与标题偏离，因为章节的内容存在交叉，如果没有用提纲来且还这些藕断丝连的关联，直接写下的内容很容易一发而不可收拾，而串行至其他章节的要点。

（3）归纳的重点偏离。

      开发者作为对细节很投入的工作者，有时候难以从全局的角度来认识我们自己正在做的产品。在写提纲时，是对产品的一个新的整体认识的过程。没有写提纲，我们会偏重于平常所关注的一些细节上。公司的某一硬件表现形式是一个机箱，机箱上有多个插卡，每个插卡的外部都有两个指示灯，用以指示当前插卡的运行状态。××在写文章时，某一章节的思路大概是这样的：

标题：指示灯

内容：

            插卡类型一。…（讲述插卡类型一的指示灯）

     插卡类型二。…（讲述插卡类型二的指示灯）

     插卡类型三。…（讲述插卡类型三的指示灯）

…

      无论从开发者还是用户指示灯都不是最核心、最重要的部分，它只是人机交互的一个简单接口。从大局的角度来看，插卡是什么？不同的插卡类型有什么样不同的功能才是我们所关注的重点。下图会表达的结构会更好。

图2

      在我看来，目录仅仅是一个粗略的提纲，满足不了文档写作的要求。我的提纲一般包括三点：目录，要点，注意事项。见下图：

 

图3

内容编写

      在有了一个完善的提纲之后，再来写文章变得比较容易，但并不是非常容易哦！我们还学要仔细考虑描述清晰完整——这一基本写作要求。在文档写作的过程中，我总结了四种结构，这四种结构能让我清晰的描述一些复杂的问题。

（1）树结构

      树结构一般用以从不同的层次来分解问题。目录、提纲都是树结构。

（2）顺序列表

      我把按顺序排列的列表结构成为顺序列表。如一个操作步骤，它是有非常明显的先后顺序。见下图。在列表的每一项前使用数字编码是最适合不过的。

 

图4

（3）平行列表

      我把与没有明显顺序的列表成为平行列表。在列表的每一项前，我觉得使用·是十分优美的，如下图。

 

图5

（4）平面方向

      使用软件时，用户直面的是一个平面（电脑屏幕）。写文档时，我们需要将平面的事物转化成文字，认识平面方向会让我们受益匪浅。在用户阅读时，一般是从左到右、从上往下。在写文档之初时，我的想法是在描述每个功能模块时，先讲解该模块显示的信息，再来描写它的操作。在初次评审时，产品经理要求按从左到右、从上往下的方向来写。对比之前自己的方式，这种方式能让用户通过文字在界面上快速的找到想要的东西。

    某项功能的操作步骤在文字上，可写成顺序列表的结构（见上面第二点），在屏幕上，它又区别于从左到右，从上到下的方向结构。使用图片来表达操作步骤是再好不过的方法了，见下图。

图6

    使用图表达步骤，要比一大堆文字或者解释清楚多了。