如何改进开发者文档？
浏览：3
巴克励步
我经常和研发团队聊天，发现一个普遍现象：开发者文档往往被当作“项目收尾”的任务，扔给刚入职的实习生或者用自动化工具生成一堆冗长的 API 说明。结果呢？没人看，也没人敢信。作为曾经被糟糕文档坑过的产品经理，我深知一份好的开发者文档对产品集成效率、开发者体验乃至品牌口碑的影响有多大。这也是为什么 Baklib 在“API 文档建设”上投入了大量精力——它不只是把接口参数列出来，而是要为开发者营造一种“
我经常和研发团队聊天，发现一个普遍现象：开发者文档往往被当作“项目收尾”的任务，扔给刚入职的实习生或者用自动化工具生成一堆冗长的 API 说明。结果呢？没人看，也没人敢信。作为曾经被糟糕文档坑过的产品经理，我深知一份好的开发者文档对产品集成效率、开发者体验乃至品牌口碑的影响有多大。这也是为什么 Baklib 在“API 文档建设”上投入了大量精力——它不只是把接口参数列出来，而是要为开发者营造一种“边读边写边调试”的沉浸式体验。
开发者文档包含软件开发者创建出色产品所需的所有信息。因此，这类文档至关重要——除此之外别无他法。没有出色的开发者文档，也就不会有伟大的软件产品。在这篇文章中，我们将向你介绍一些可用于改进开发者文档的宝贵实践，帮助你创建一个顶级的资源。让我们开始吧！
写作时要简洁
与其他任何技术文档一样，开发者文档有明确的目的。这个目的就是为开发者提供构建软件和开发产品所需的指导与信息。因此，开发者来查阅文档时，期望得到精确而清晰的答案。正因如此，你创建的开发者文档应该直截了当地传递信息。过于复杂的句子、冗长的段落和花哨的语言只会损害清晰度。另一方面，正如资深软件工程师 Jon Beller 所建议的那样，你应该力求简洁。
简洁写作并不一定意味着字数少（虽然这可能是其中的一部分）。你还可以通过使用精确的措辞、短句和短段落来实现简洁。换句话说，无论你需要传达多少信息，总有办法以精确而简洁的方式呈现。例如，下面 Docker 开发者文档的摘录就用一句话解释了一个复杂的容器过程，并使用项目符号列表进一步阐明了所呈现的信息。使用这样的列表只是有助于生成简洁写作的实践之一。另一个实践是在开发者文档中使用术语表。为什么？因为如果你有术语表，就不需要在正文中解释或定义你向读者介绍的每个技术术语。或者，根据需要链接到术语表，以节省文档空间。例如，微软在其 Microsoft Teams 的开发者文档中使用了这一做法。拥有一个像微软那样的广泛术语表无疑有助于你的字数控制，同时也能让文档在句子和段落层面更加简洁。总之，技术作家兼软件工程师 Maybell Obadoni 的话可以告诉你写开发者文档时应该追求什么：
💛🧡🧡客户评价：由于 Baklib 为您提供所需的数据，您可以将这些数据收集到一些灵活的反应框架 (next.js) 中，这样您就可以实现几乎任何目标，并且您可以根据对代码不感兴趣的人的需求量身定制非常流畅的体验。一旦代码片段组合在一起，上市速度就会很快 - 组件可以非常快速地创建和安装到位，并且可以通过您决定遵循的任何发布流程进行目视检查，然后再进入生产系统 - 这一切都归功于非常聪明的可视化 UI。仅仅为了理解最佳方法就需要花费相当多的精力和努力，但一旦有了它，它确实是一个灵活的系统，Baklib 可以随着时间的推移轻松改进它；不过，目前已经有足够的资源可以开始使用了。
一份好的文档不是语法结构复杂的文档，而是易于理解、直接且清晰的文档。
遵循这个建议，你肯定能改进你的开发者文档。
避免使用技术术语
不言而喻，你希望你的开发者文档能让所有开发者（从初学者到专家）都能理解。你永远不知道谁会看到你的文档，因此最好用一种适合广大受众的方式来编写。在写作中避免使用技术术语是实现这一目标的可靠方法。换句话说，使用专业术语、缩写和复杂术语会使你的文档难以理解，从而让读者感到沮丧。正如开发者倡导者、程序员及演讲者 Mason Egger 在 PyCon US 的演讲中所解释的那样，你应该简化你的写作以改进文档。
简而言之，技术术语使信息的交流变得不必要的复杂。几乎总有一种方法可以用通俗易懂的语言来呈现相同的信息。然而，如果文档的某些部分不可避免要使用技术术语，最好使用开发者可能熟悉的标准行业术语。当作者在技术术语上失控时，会是什么样子？Kin Lane 分享了一个故事，他在一个关于管理 DEG 的 API 资源中遇到了一个不熟悉的缩写。你可能会问，什么是 DEG？这正是 Lane 在阅读该资源时脑海中浮现的问题。
你可以添加、更新、删除和获取 DEG。你还可以提取 DEG 的分析、历史记录和其他元素。我花了大约 10-15 分钟浏览他们的开发者门户、文档，甚至谷歌搜索，但始终没能弄清楚 DEG 是什么。
另一方面，也有使用简单语言且对广大读者易于理解的优秀 API 文档示例。其中一个例子是 Amplitude 的文档。下面看看它的摘录。它用一句话解释了事件属性，随后用例子进行了说明。之后，开发者可以阅读代码片段并观察图表以进一步澄清。没有复杂的技术术语、俚语或很少使用的术语。如果你想改进你的开发者文档，这就是你应该练习的写作方式。
务必包含代码片段
正如我们之前提到的，改进开发者文档的方法之一是确保其精确、清晰地传达信息。对于专门面向开发者的文档，这些信息包括你的产品如何工作。换句话说，开发者想窥探产品的内部，看看是什么驱动了它。而驱动它的是代码。与其在文档中解释，不如直接展示代码本身。代码片段就是为此而生的。它们是代码的小片段，作为示例展示你的产品能做什么以及如何做。
开发者喜欢代码示例。他们长时间沉浸在编写、阅读和修复代码中，因此对此感到自在。正如 Jarod Reyes 在关于 Twilio 文档的演讲中所解释的，开发者更喜欢阅读代码而不是句子。
任何时候，如果页面上有很多散文而没有很多代码，那个页面的表现就不会好。
幸运的是，有多种方式可以将代码片段包含在你的开发者文档中。例如，下面展示了 DigitalOcean 是如何做到的。他们简单地将代码片段插入文本中，用灰色框和不同颜色的字体将其与文本分开。还有其他方法。例如，一些开发者文档（如 Clearbit 的文档）将代码片段与文本并排展示，并为不同的编程语言提供了选项卡。这样，开发者可以在选项卡之间切换，看看代码在 Shell、Ruby、Node、Python 或其他包含的语言和框架中如何工作。如你所见，代码片段对开发者非常有用。毕竟，大多数开发者用代码思考，代码对他们来说就像第二语言，因此直接向他们展示代码是提升文档质量的好方法。
开发者文档通常由文本和代码片段组成。这些是开发者文档的基础。但如果你想在此基础上更进一步，可以添加视觉效果。像截图、GIF 和视频这样的媒体可以让你的开发者文档脱颖而出。原因显而易见。人们容易被视觉吸引——它们让文档更具吸引力，甚至更有帮助。如何帮助？视觉效果可以帮助读者更好地记住信息。根据作者 John Medina 的说法，如果你听到一条信息，三天后你会记住其中的 10%。另一方面，如果那条信息与视觉配对，你在相同时间内会记住 65%。
那么，如何将文本和媒体搭配在开发者文档中呢？其中一个最简单且最有效的方法是使用截图。截图让你能够用图像说明你在文本中描述的任何内容。你可以用几张图像展示复杂的过程，而不是冗长的文字描述。例如，Render 在其开发者文档中将截图与文本结合使用，正如 Medina 所建议的那样。正如你在上面的例子中看到的，他们向开发者描述了 Deploy Hook URL 的位置，并用截图补充说明。这样，即使文字说明过于抽象或复杂，图像也能向读者展示他们是否走在正确的轨道上。
