资深工程师教你写出研发喜欢的文档

作者｜David Cassel

链接｜https://thenewstack.io/an-engineers-best-tips-for-writing-documentation-devs-love

看一位热情的演讲者分享他们学到的东西是很有趣的一件事。今年早些时候，Mayson Egger（https://github.com/MasonEgger） 作为演讲者参加了 PyCon 2022 大会（https://us.pycon.org/2022/），他曾是一位工程师，后来成为 Gretel.AI（https://gretel.ai/） 的首席开发者大使。Gretel.AI 是一个提供合成 / 隐私保护数据的平台。

在加入 Gretel 之前，Egger 是 DigitalOcean（https://www.digitalocean.com/） 的开发者布道师和社区作者，他告诉观众，「我今天要教给你们的所有东西都是在那里学到的。」

除此之外，Egger在每年的 Hacktoberfest（https://hacktoberfest.digitalocean.com/） （DigitalOcean 发起的一个推广、支持开源的年度在线活动）都会贡献技术文档，他的幻灯片也得到了来自DigitalOcean 的专业编辑指导。

「DigitalOcean 的教程太棒了，如果你从未看过或使用过它们，一定要去，」Egger 告诉他的观众。事实上，在 TNS，我们发现 DigitalOcean 就同一主题提供的文档通常比其他大型云服务提供商的文档更容易理解。

「在那里，许多优秀的人教会了我大量关于编写文档的知识。现在我想与你们分享。」

达成现实世界中的目标

写作者应该珍惜读者的时间，并始终努力抓住重点。

Kurt Vonnegut 曾建议小说作家，为了加快进度，每个角色都应该渴望一些东西。与此类似，Egger 的第一条建议是建立一个文档将帮助读者实现的清晰目标。Egger 警告说：「不要花时间去夸大你的技术。如果开发者想读小说，他们会去读小说！开发者读文档是来解决问题的。」

因此，假如你真的写了大段推销产品的夸张内容，「无论如何，他们都会跳过这一部分。」

正因如此，由于很多读者会直接跳转到代码示例，Egger 认为示例应始终体现现实世界中的问题。

当 Egger 问道：「你们中有多少人读过搜索到的每个 Stack Overflow 上的解释？有多少人滑到页面的下半部分只看了答案，甚至没有读背后的文字？请举手。我也这么做过。」

写作者应该珍惜读者的时间，并始终努力抓住重点。

「人们会跳过文字去看代码！所以请确保你的代码可以解决现实世界中的问题……」

Egger 后来说，考虑到那些读者工作繁忙，他最重要的建议是始终在发布文档之前验证指导说明。

「比没有文档更糟糕的事情是有错误文档，」他说，「因为没有文档意味着我要去其他地方找，而错误文档浪费了我的时间。」

Egger 用只有在文档作者机器上才能工作的指令场景逗笑了观众。有什么解决方案呢？在另一个开发者的环境中进行测试，并让其他人跟着你的文档操作。

事实上，Egger 甚至认为，应该始终对文档进行组织布局，以便读者能够轻松地浏览文档中的特定信息块，包括标题和副标题，并以粗体突出显示库名。

「这又回到 Stack Overflow 的例子上，」Egger 说。

出于同样的原因，Egger 建议为文档编写目录。浏览文档的人「正努力非常快地解决一个很具体的问题。如果他们已经点开了你的文档，但在 30 秒内没有找到答案，他们将选择 Stack Overflow。」

「唯一比没有文档更糟糕的事情是有错误的文档」

Egger 认为，网站访问者平均在一个网站上花费约 6 秒钟。「他们点击网站，寻找他们需要的东西，如果找不到，他们就会离开。这种情况是常态。」

在这一点上，Egger 的想法似乎呼应了给小说作家的另一条常见建议：「不要告诉别人你的程序库能做什么，而是要向人们演示……」

为了帮助说明，Egger 提醒观众要选择有意义的变量名。「Foo 和 Bar 都没用，」Egger 说。「它们应该被删掉！不要用它们！这些东西毫无意义。」

Egger 后来开玩笑道，他对这件事的态度非常强烈，去掉 Foo 和 Bar 「将成为我竞选总统时的竞选口号。」

包容性和可读性

四月，美联社在下一版的风格指南中发布（https://www.apstylebook.com/blog_posts/18）了关于「包容性叙述」的新章节。Egger 分享了他自己编写包容性文档的方法。首先要避免使用诸如 「菜鸟」之类不友好的词语，甚至是例如「简单」或「容易」之类的评判性词语，因为对某人来说「简单」或「容易」的内容可能会对其他人构成挑战。

「你会惊讶地发现，有多少人因为看到别人告诉他们很简单的事情对他们来说并不简单而感到厌烦。这让他们对整个项目都失去了兴趣。」

文档还应该避免性别化语言，Egger 建议的一种简单方法是只使用如「 你 / you」的第二人称代词。Egger 用一个玩笑阐明了自己的观点。他说道，作为一个得克萨斯州人，当需要使用第二人称复数代词时，他也喜欢「y'all」这个词。在 2021 年线上 All Things Open 大会上，Egger 甚至发表了 12 分钟的演讲，他认为这种常见的德式收缩（在德克萨斯州常见的语言压缩）也会使文档和社区更具包容性。

「你会惊讶地发现，有多少人因为看到别人告诉他们很简单的事情对他们来说并不简单而感到厌烦。这让他们对整个项目都失去了兴趣。」

实现包容性的一种简单方法就是确保所有人都能理解文档。Egger 建议降低文档的适用阅读水平，比如定在三年级水平，同时避免「SAT单词」，即「没有人再在普通白话中使用」这些出现在学术测试中的晦涩单词。但同样，Egger也建议避免过多使用只有专业群体理解的行话。（Egger 指出，「行话这个词本身就是行话，我觉得很搞笑。」）关于这点，Egger 快速提及了一句话来全面总结：

「用人们说话的方式来写作，他们就能更好地使用你的文档。」

事实上，Egger建议在写文档时应假设你的读者完全都是初学者，除非你确认目标读者的水平更高。

同样的道理：应避免提及修辞和流行文化，因为全球读者可能不熟悉这些内容。虽然 Egger 自己也喜欢网络流行语，「但在包容性文档中，应该尽量避免使用网络流行语。」

这给 Egger 带来一个更恼火的问题。另一张幻灯片指出：「科技领域的首字母缩略词太多了。」「一些首字母缩略词甚至有两个或三个意思，」Egger 告诉观众，并补充道，首字母缩略词可能会让初学者望而生畏。

Egger 笑着告诉观众：「我花了更多时间害怕缩略语，因为缩略语而不使用科技。我希望看到它们全部消失，至少在以初学者为中心的内容中消失。」

与 AP Stylebook（https://www.codot.gov/business/grants/safetygrants/assets/APStyleGuideCheatSheet.pdf） 一样，Egger 建议首次使用首字母缩略词时标注全名。Egger 甚至会在文档的开头或结尾提供首字母缩略词和它们的定义。

「完全可以制作一个词汇表」Egger 对观众讲道。