技术文档不必枯燥

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

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

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

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

想想你喜欢阅读哪种文档，然后就那样写。如果人们不喜欢，你肯定会知道的。