2011年技术文档写作年终总结系列之一：协作与反馈

目前公司包括我在内就两个人在负责技术文档的维护。虽然只有两个人，也是要讲究协作和反馈的。

由于我们采用Docbook作为写作工具，用CVS对源文件进行管理，这让多人协作非常方便，因为我们可以同时编辑同一个xml文件。如果是使用MS Word来编辑的话，多人同时编辑同一个文件简直就是不可想象的。

通常情况下，我们会先根据目标任务来列出一张to-do list，详细标明哪些内容需要修改，修改的依据（如具体的需求来源，内部缺陷跟踪管理系统的事件ID号），由谁来修改，等等。我曾经想研究下用什么to-do类工具来支持这类工作， 最后发现其实没必要那么复杂，一张excel表格就够了，毕竟我们只有两个人。

明确了要做的任务后，即可动手修改现有用户手册了。完成一个小目标（如一个新功能的介绍）后，一般要发邮件让对方帮忙review，主要是从使用者的角度来看是否写得清晰。如果要描述的对象比较复杂或者自己不敢肯定的，还要抄送给负责测试的MM，让她们也瞧一下（虽然多数时候可能她们都不会去看……）。所谓当局者迷，盘观者清，其实由不熟悉产品的人来review反而会有更好的效果，他们往往会发现一些容易被我们这些technical writer忽略的细节问题（因为我们对产品了解到一定程度后，难免会有一些想当然的想法）。只是现实是，在公司内部这是很难办到的，毕竟其他人也有自己的工作，无暇帮忙检查文档质量。

客服那边有时候也会有人发邮件过来问一些问题，因为她们需要截取一些文档片段来回复客户的咨询。这也算是一种反馈吧。其实，哪怕是只指出一个标点符号或者单词拼写的问题，我们也是很欢迎的。也许人都是怕麻烦的，可能不会有多少人愿意因为看到用户手册有一个标点符号的错误而发邮件给我们；也可能是因为不好意思，怕被人说是吹毛求疵？其实我们真的不介意的。

至于客户那边的反馈，实际上，我猜很多客户都是不看文档的，直接就发邮件来客服咨询。即便如此，客户咨询单也是能给我们提供一些反馈的。例如，客户在使用功能A的过程中，对关联的功能B有疑问，但实际上功能B在用户手册中其实是有详细描述的。这个情形对我们有何启示呢？我们需要检查在描述功能A的章节那里，有没有足够明确的提示信息关联到功能B；或者，有需要的话，可以直接将功能B转移或者复制一份内容到功能A所在的章节，这样一来用户就不用循着链接来回查看了。在没有必要补充内容的情形下，依然可以做出改进，如将一些重要的描述改为醒目的提示样式，而不是把它们混在普通的正文介绍中。在没有新功能更新的时候，我们就是靠深入挖掘客户咨询单来获得反馈，然后持续改进现有文档的。

其实不只是技术文档写作，任何工作都需要有效和足够的反馈，才能做出更有针对性的改进。