魔鬼在于细节

Technical writer在写用户手册时容易出现的问题就是,想当然地以为某个功能或者说操作步骤是显而易见、无需过多描述的,可有时候往往这些细节对用户而言才是关键所在。

前几天我在更新某个功能的用户手册时,碰到了点问题。去年还是前年,我更新过关于这个功能的介绍,因此基本操作步骤我还是有印象的。操作了两三遍,都碰到系统报错问题。我怀疑这是一个系统bug,于是发了邮件向QA请教。专家一出场,很快就从我邮件中的问题描述以及截图中看出问题所在:我使用的测试用户权限有问题。

具体的说呢,在我们的产品中,用户分为内部和外部两大类,而外部用户又有可登录与不可登录之分。通常为图省事,在测试与外部用户相关的某些功能时,我都习惯简单地创建一个不可登录用户。那问题就来了,在我测试的这个功能中,外部用户必须是可登录用户,但我没有意识到我正在使用的外部用户是不可登录的。其实系统的报错信息也是有相关提示的,只不过那条信息把几种可能的情形糅合在一起,我没留意看……

再次检查一遍我以前写过的文档,发现我并没有把这个细节写进去。估计当时我碰巧用的是外部可登录用户做测试,所以没有遇到这个报错的情形。于是,我把这个注意点补充进文档了,还特意用粗体效果高亮出来。

联想到前几天看到的一篇文章,这事儿还可以从另一个角度来解读。在刘未鹏《逃出你的肖申克》系列最新一篇文章《看不见的牢笼(上)》中,他提到了一个有趣的现象,名为“知识的诅咒”:由于知道某个知识,反而影响了判断。以我的情形来说,我并不是不知道我们公司的产品中有“可登录用户”与“不可登录用户”这些概念,只是因为它们是最基础的功能,看起来十分简单,所以我潜意识里把它们的重要性给忽略掉了,想当然地以为用户肯定不需要我在用户手册中重复提到这些细节。可现实是,写用户手册的我,反而在操作上会遇到麻烦而不知道问题出在哪里,汗……想象一下,如果我是我们公司产品的全新用户,如果按照用户手册来测试这个功能的话,很有可能也会一头雾水(假设我刚好使用的是不可登录用户)。

此外,这件事也说明了,文档是需要作者以外的其他人(最好是对特定功能不熟悉的人)帮忙review才容易发现问题。

西方有句谚语叫做The devil is in the detail。在写了两年多的技术文档后,我愈发深刻地体会到这句话的真谛。

发表评论

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