Technical writer在写用户手册时容易出现的问题就是，想当然地以为某个功能或者说操作步骤是显而易见、无需过多描述的，可有时候往往这些细节对用户而言才是关键所在。
前几天我在更新某个功能的用户手册时，碰到了点问题。去年还是前年，我更新过关于这个功能的介绍，因此基本操作步骤我还是有印象的。操作了两三遍，都碰到系统报错问题。我怀疑这是一个系统bug，于是发了邮件向QA请教。专家一出场，很快就从我邮件中的问题描述以及截图中看出问题所在：我使用的测试用户权限有问题。
具体的说呢，在我们的产品中，用户分为内部和外部两大类，而外部用户又有可登录与不可登录之分。通常为图省事，在测试与外部用户相关的某些功能时，我都习惯简单地创建一个不可登录用户。那问题就来了，在我测试的这个功能中，外部用户必须是可登录用户，但我没有意识到我正在使用的外部用户是不可登录的。其实系统的报错信息也是有相关提示的，只不过那条信息把几种可能的情形糅合在一起，我没留意看……
再次检查一遍我以前写过的文档，发现我并没有把这个细节写进去。估计当时我碰巧用的是外部可登录用户做测试，所以没有遇到这个报错的情形。于是，我把这个注意点补充进文档了，还特意用粗体效果高亮出来。
联想到前几天看到的一篇文章，这事儿还可以从另一个角度来解读。在刘未鹏《逃出你的肖申克》系列最新一篇文章《看不见的牢笼（上）》中，他提到了一个有趣的现象，名为“知识的诅咒”：由于知道某个知识，反而影响了判断。以我的情形来说，我并不是不知道我们公司的产品中有“可登录用户”与“不可登录用户”这些概念，只是因为它们是最基础的功能，看起来十分简单，所以我潜意识里把它们的重要性给忽略掉了，想当然地以为用户肯定不需要我在用户手册中重复提到这些细节。可现实是，写用户手册的我，反而在操作上会遇到麻烦而不知道问题出在哪里，汗……想象一下，如果我是我们公司产品的全新用户，如果按照用户手册来测试这个功能的话，很有可能也会一头雾水（假设我刚好使用的是不可登录用户）。
此外，这件事也说明了，文档是需要作者以外的其他人（最好是对特定功能不熟悉的人）帮忙review才容易发现问题。
西方有句谚语叫做The devil is in the detail。在写了两年多的技术文档后，我愈发深刻地体会到这句话的真谛。