技术文档最佳实践：你可以遵循的准则
浏览：0
巴克励步
我经常听到团队抱怨技术文档要么写得晦涩难懂，要么干脆缺失，导致开发效率低下。作为产品经理，我深知文档不仅仅是代码的说明书，更是产品与开发者之间的沟通桥梁。在帮助多家企业搭建产品手册的过程中，我发现好的文档需要兼顾不同角色的需求——从初级工程师到架构师，每个人都需要在文档中快速找到自己需要的信息。今天，我想聊聊技术文档建设中的那些最佳实践，希望能帮你避免常见的坑，真正让文档成为团队协作的加速器。 确定
我经常听到团队抱怨技术文档要么写得晦涩难懂，要么干脆缺失，导致开发效率低下。作为产品经理，我深知文档不仅仅是代码的说明书，更是产品与开发者之间的沟通桥梁。在帮助多家企业搭建产品手册的过程中，我发现好的文档需要兼顾不同角色的需求——从初级工程师到架构师，每个人都需要在文档中快速找到自己需要的信息。今天，我想聊聊技术文档建设中的那些最佳实践，希望能帮你避免常见的坑，真正让文档成为团队协作的加速器。
确定你的技术文档用户
识别技术文档的用户听起来很简单，尤其是当你的目标是组织内部文档时。但你仍然需要记住，不同类型的开发者会使用这些文档，并相应地调整内容。
软件工程师 BJ Rutledge 在 LinkedIn 上发帖讨论了技术文档的重要性。他给出的建议之一是“花时间考虑读者”。
一种解读是：针对不同的专业水平采用不同的写作风格。例如，如果知道很多初级工程师会阅读你的技术文档，你可以侧重于教程、示例和指南。相反，如果主要受众是资深开发者，那么包含语法、参数和响应细节会更有用。
💛🧡🧡客户评价：我想要一种简单的方法来发布资产并通过 API 将其附加到内容，每次交互重新发布使得从我的个人仪表板管理内容变得更加复杂。
不过，按资历调整写作风格并非唯一策略。你也可以让文档撰写者考虑不同专业背景的同行。
以 GitHub 的 REST API 文档为例。GitHub 在其 API 中使用了 OAuth2 标准。很可能是一位后端工程师编写了这份文档。在这种情况下，作者可以仅仅说明公司使用 OAuth2 进行在线授权，所有后端和全栈开发者都能理解。然而，并非所有读者都有相同的背景。因此，关于 OAuth2 的文档包含了链接，帮助移动端等所有开发者理解这一标准。
总之，你的团队可能由出色的开发者组成，但你仍然需要思考具体谁会阅读这份文档。不确定时，最佳实践是从基础水平开始编写文档。
为初级用户编写文档
以初级用户易于理解的方式编写内部技术文档，并不意味着你低估了自己的开发者。相反，简单易懂的文档能让他们快速掌握 API 并轻松使用。
一个常见的建议是：为初级用户编写外部技术文档，以便不同背景的读者都能理解。例如，你希望不具备技术知识的记者也能撰写关于你公司的文章。同样，清晰的技术文档能让其他企业的 CTO 或解决方案架构师快速判断你的 API 是否适合他们。
现在来看看 HubSpot 的 CRM API 文档是如何清晰简洁地呈现的。标题下方就是 API 描述，无需猜测本节内容。接下来是代码示例，让开发者看到 API 的典型应用。最后是一列伪属性值，让开发者知道从请求中能获得哪些值。注意 HubSpot 如何通过简洁的信息实现清晰，而不是提供复杂的解释。
软件测试公司 CIO Slava Fioletov 表示，保持信息简洁是软件文档的最佳实践之一：“记住，文档不必冗长。它的任务是用简单易懂的语言全面描述项目。”
为初级用户编写的另一个技巧是避免过度使用行话。如果让开发人员编写技术文档，你很可能得到一份充满行话的高级文档，因为他们假设每个团队成员都有相同的知识。但是，从初级到资深开发者都应该能理解你的文档，你可以通过聘请技术写手来克服这一挑战。你的开发者可以贡献代码示例，但明智的做法是聘请一位客观的审阅者，确保文档真正易于理解。
采用行业标准布局
正如你鼓励内部开发团队保持一致的编码规范一样，你可以采用行业标准的技术文档布局来匹配这一期望。标准化布局是帮助开发者轻松浏览文档的最佳方式。
虽然类和函数的列表确实包含有助于理解 API 的材料，但这种格式绝非直观或易于操作。以 OpenCV 的 API 文档为例。页面上只列出了类，还有一些函数，但没有提供任何解释或上下文。如果你的文档看起来像这样，开发者即使能找到信息也会很困难。
更好的方法是研究行业标准的文档布局并模仿它们。例如，如果你正在为 iOS API 构建文档，最好先查看 Apple 的 API 文档。注意文档组织的常见模式，然后模仿这些布局。
如果你不想花太多时间从头配置布局，可以考虑使用技术文档工具。Swagger 是一个不错的选择，它是一套由 SmartBear 支持的 API 开发者工具。除了生成文档，Swagger 还维护多个版本，让开发者能快速找到所有可用版本及对应文档。
如果你选择使用 Baklib 的产品文档系统，你可以将 Swagger API 文档集成到知识库中，使所有团队成员都能轻松访问。
包含基本章节
与选择标准文档布局类似，所有技术文档都应包含基本章节，以便开发团队全面了解 API。Postman 的《2021 年 API 现状报告》显示，只有 3% 的受访者对他们使用的 API 感到满意。当被问及改进建议时，受访者列出了他们希望看到更多内容：更好的示例和示例代码，以及文档标准化。
因此，知道开发者希望看到更好的示例和代码后，你应确保在文档中适当包含这些内容。以 Stripe 的 API 文档为例，它包含了开发者所需的所有要素：简洁的 API 描述、根据所选库变化的代码示例、参数描述等。
当然，不同 API 需要包含的章节会有所不同，但大多数文档中都包含以下要素：
- 资源描述
- 资源 URL
- 代码示例
- 端点和方法
- 参数
- 请求示例
- 响应示例
- 状态和错误代码
用资源丰富你的文档
一图胜千言，构建技术文档的最佳实践之一是用截图或代码示例等资源来丰富它。API 描述和错误信息可能是文档中的关键要素，但用其他资源补充总是值得的，尤其是当 API 包含 UI 元素时。
以 GitHub REST API 文档中关于使用身份验证应用的部分为例。该文档包含了截图，清楚展示了每个步骤。通过包含这些截图，GitHub 使整个过程易于理解，即使是不熟悉身份验证应用的开发者也能明白。此外，文档还提供了代码示例和指向相关资源的链接。
最后，别忘了在文档中加入常见错误及解决方法。你不可能预见所有问题，但编写一份常见错误列表能帮助开发者在遇到问题时快速解决。这不仅能节省你的支持时间，还能改善开发者体验。
