技术文档不必枯燥

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

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

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

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

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