技术文档不必枯燥

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

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

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

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

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