打造优秀开发者文档的6个技巧

在所有伴随软件产品的技术文档中，开发者文档可能是最重要的一种。

为什么？很简单——因为它帮助开发者完成工作。当开发者能够尽力做好工作时，优秀的软件产品就诞生了。

开发者文档旨在为他们提供所需的一切知识。

如何创建这样一份高质量的文档？继续读下去吧！

如果你问十几个开发者如何格式化文档中的文本、使用哪些缩写、编写代码示例时采用什么缩进，你可能得不到两个相同的答案。即便他们在同一个团队工作，这种情况也可能发生。因此，你应该考虑为文档创建一份风格指南。

风格指南可以消除开发者文档一致性方面的所有问题。当多位开发者为文档做贡献时，这一点尤为重要。有了风格指南，他们就能清楚知道自己的写作应如何呈现。正如 GNOME 的风格指南所解释的，这将带来出色的结果。

这样的资源让编写和阅读开发者文档都变得更容易。贡献者知道如何编写和塑造文档，读者则能得到一致且易于理解的文档。不过，创建风格指南并不意味着你需要撰写一部百科全书，详细规定每一个空格和逗号。

例如，GNOME 的风格指南涵盖以下方面的指导原则：

每个类别都有子类别，但指导原则大多宽泛直接。例如，看一下关于编写代码示例的说明。它们进一步提出了一些建议，但如上所示，这些指导并不严格。或者，如果你愿意，也可以制定更详细的风格指南。MDN Web Docs 就有一份全面的指南，提供了更精确的说明和示例。他们对代码示例样式的指南包含了缩进、间距、代码行长度等具体规定。无论你选择简单还是综合的指南，创建它都能极大地帮助所有参与编写的人。

开发者文档可能非常庞大。需要覆盖的内容很多，如果你打算为开发者创建一份全面资源，那可能累积成几十份甚至上百份文档。这可能会让读者不知所措。大多数人只想快速获取所需信息，却突然面对多个类别、子类别和文档。一个解决方案是以直观有效的方式组织文档，例如将其分为编码文档和测试文档。

这两个集群可以为开发者提供一个清晰的阅读起点。编码文档展示软件如何工作。开发者记录代码，以便其他人更容易浏览、使用和重现代码。例如，Express.js 的 ReadME 文件就是编码文档的一个例子。它提供了框架安装、使用、运行示例等信息。另一方面，测试文档解释产品如何被验证。测试是一个重要且详细的过程，因此需要全面的文档。测试文档中有许多不同的文档，如测试计划——它列出软件测试活动、时间表、策略、所需资源等。测试计划是应该具备的基础测试文档之一，因为它确保了对软件产品进行结构化测试的方法。将开发者文档分为编码和测试两大集群可以使其更有条理、更易访问。

优秀的开发者文档是所有人都能理解的。这个说法听起来或许很明显，但有时作者写作时并不使用平实的语言。当你用直白、不过度复杂的方式写作时，你就能确保信息传达给所有受众。开发者文档的受众具有一定技术知识，但新手和专家水平不同。使用平实语言很重要：无论是对入职第一天的初级程序员还是经验丰富的软件工程师，文档都易于理解。否则，作者可能会用晦涩的缩写和专业术语使文档变得枯燥难用。

Stripe 的开发者文档是备受推崇的例子之一。他们使用易懂清晰的语言。例如，关于元数据的文档：第一段介绍上下文，解释元数据参数的用途；第二段简要说明参数可能的样子。注意 Stripe 在定义或陈述后如何提供示例，这进一步澄清了内容。使用这样的平实语言对于编写顶级开发者文档至关重要。

可以说大多数开发者都喜欢写代码。但并不意味着他们喜欢浪费时间写代码。如果有可能简化编码的例行部分并节省时间用于更有创造性的任务，他们会接受。你可以通过在文档中包含代码片段来给他们这样的机会。Julien Delange 解释了什么是代码片段：它们的关键优势在于可重用。开发者可以使用这些现成的代码块，而无需从头编写每一行。这使工作更快、更容易，也更一致。使用相同的代码片段可以最大限度地减少错误，确团队代码的一致性。

例如，Mailchimp 在其文档中为各种功能使用了代码片段。如果开发者想添加联系人，只需复制代码片段并填写必要信息即可。他们不需要记住格式或语法，减少了出错的可能。使用代码块也比每次编写要快得多。

创建优秀的开发者文档需要关注一致性、组织性、语言清晰性和实用性。通过应用这些技巧，你可以帮助开发者更快更好地工作，从而提升产品体验。Baklib 提供了强大的文档平台，帮助你轻松构建和管理开发者文档、API 文档等知识门户，支持 AI 搜索和富内容发布，让知识沉淀与共享变得简单。

---

Baklib 是新一代数字内容体验管理平台。竞争环境充斥着“可组合”、“无头”和“DXP”解决方案 --- 但无头选项虽然易于开发人员构建，但为跨职能团队留下了巨大空白，并且无法解决所有用例。Baklib 弥补了依赖开发人员但灵活的无头解决方案与不适合复杂项目的更传统、更适合营销人员的选项之间的差距。