技术文档不必枯燥

今年早些时候，我描述了优秀文档的三个重要特征：简洁、一致和简单。 我写道，好的措辞对于理解和翻译非常重要。 但这并不意味着它必须枯燥乏味。

想知道一个秘密吗？ 我最喜欢的科技书籍是 For Dummies 系列。 和你们许多人一样，我的书架上也有不少 O'Reilly 的书，它们都很棒。 我从我拥有的严肃科技书籍中学到了很多东西，但是当我要坐下来学习一个不熟悉的科目时，幽默的书籍最能吸引我的注意力。 如果你想让我关注你的文档，保持我兴趣的最佳方法是大量使用“空前绝后满天飞！”的梗。 看来我选错了星期来戒掉 [装订] 胶水。

让你项目的个性融入文档是可以的，甚至是有益的，但有一些注意事项。 要注意在另一种语言，甚至同一种语言的不同方言中没有意义的口语表达。 要知道你诙谐的流行文化典故可能会被错过，或者不被认为有趣（是的，甚至有人不喜欢“空前绝后满天飞！”）。 目标不是试图变得有趣，而是允许你自己的风格。 正如 Bob Reselman 在 关于他在 SCaLE 14x 演讲的采访 中告诉 Rikki Endsley 的那样：“枯燥乏味真糟糕。”

但与生活中的大多数事情一样，也有例外。 枯燥乏味对于参考资料来说很棒：API 文档（尽管可以在示例中随意展示个性）、词汇表和发行说明。

想想你喜欢阅读哪种文档，然后就写那种文档。 如果人们不喜欢它，你可以肯定他们会让你知道。