获奖的 devportal 不仅仅是文字

Source: Dev.to

“对担任开发者内容负责人三年的反思。”

Viam 文档涵盖了一个复杂且庞大的开发者平台、多语言 SDK，以及以初创公司速度迭代的 API。正因如此，这些文档获得了多个奖项。

但它是从哪里开始的呢？这段 Web Archive capture 展示了三年前的样子，也就是我加入之前的模样。

我的团队和我开始着手改进，一年后，这个谦逊的起点已经转变为值得阅读的文档。我们在 Devportal Awards 中赢得了多个奖项，其中包括 最佳整体 SME 开发者门户 奖——参见 LinkedIn 帖子。我们走在了正确的轨道上。

改进文档网站

一个优秀的文档门户不仅仅是技术写作；它还是用户每天交互的网站。考虑到这一点，我们加入了若干可用性功能。

• 用于过滤更新日志条目、教程和模块的动态元素（模块早在产品之前就已实现）。
  通过 Typesense（开源搜索引擎）和 Algolia 的 InstantSearch.js（开源 UI 库）的组合，我们得以在本来静态的站点上添加这些组件。

• 在文本中显示的术语表项，悬停时展示更多信息。
  Hugo 是一个在不使用完整前端框架的情况下实现自定义的文档站点的绝佳框架。我借鉴了 Kubernetes 作者们的工作（同样使用 Hugo）。

• 使用 GIF 动图展示功能和硬件的实际运行。
  我很早就决定依赖图像来让产品栩栩如生，因为硬件动作最适合用视觉方式传达。借助 Hugo，我添加了短代码，将 GIF 以省带宽的视频形式呈现，并广泛使用 Hugo 来强制执行 SEO 规则。

使用 GitHub Actions 实现自动化

在为一个复杂平台保持文档覆盖面最新的同时，还要维护面向用户的 Web 应用，这对小团队来说并非易事。我们大量依赖自动化，主要通过 GitHub Actions：

• 使用 Vale 进行风格指南检查 – 一个专注于正文的 linter。通过创建覆盖我们风格指南规则的正则表达式，Vale 能自动标记违规之处。我最初在 MongoDB 发现 Vale，并用它编写了至今仍在使用的规则（我的 Vale 仓库；随后社区将其发布为 mongodb‑vale‑action）。

• 代码示例测试 – 我构建了一个测试套件，将代码示例放入带有项目初始化/清理以及标记每个示例的文件中。GitHub Actions 和 Bash 脚本随后运行这些测试，并从标记中生成最终的示例。前期投入得到了回报：端到端测试能够捕获 API 变更和服务中断，让我们对发布的代码充满信心。

• 失效链接检测与转发 – htmltest 在检测断链方面表现出色，但处理已迁移的链接需要额外工作。我通过 Netlify 集成（“No more 404s” 插件）解决了这个问题。Netlify 还帮助我们将 HTML 级别的重定向迁移到真正的 HTTP 级别转发。

生成式 AI

我们也对生成式 AI 进行了大量实验。我构建了一个概念验证工具，能够根据 PR 中的信息自动更新文档，随后又发现有一家供应商能够做得更好。虽然 AI 生成的内容仍然需要严格审查，但它是一个有前景的方向。AI 聊天模型已经变得更加先进，我对它们的实用性感到惊讶——前提是使用时保持谨慎。

Fact‑Checking 的新出现
我常常希望人们把生成式 AI 的输出视为一种不同的搜索方式，因为这种视角能让批判性审查的需求始终摆在前面。作为整个行业，我们仍需提升用户对生成式 AI 工作原理的认知——用户往往期待它具备实际上没有的能力，甚至把密码和机密信息交给 AI 聊天。

我们从 AI 使用中得到的经验完全可以写成多篇博客，所以这里简要说明：如果你在寻找预构建、可嵌入的 AI 聊天工具，我推荐 Inkeep。

单一真相来源：SDK 文档 与 “主” 文档

我们利用自动文档生成来减轻工作负担。例如，我们自动从 SDK 文档生成主平台文档。当我意识到有人在 SDK 文档和主文档之间来回复制代码示例时，我推动实现单一真相来源。

• 代码示例的归属位置： 演示如何使用单个 API 函数的示例应放在 SDK 中。
• 实现方式： SDK 文档是从 SDK 代码中的 docstring 生成的，这样文档与代码共存，更容易保持最新。
• 工作流程： 我们构建了一个系统，摄取 SDK 文档并自动生成主文档的部分内容。系统运行时，我们可以看到并审查新更改，并在需要时编辑 SDK 文档。

结果是更高的一致性和更少的手动工作。

结论

虽然文档不是我唯一工作的内容，但它们是我最自豪的成果。三年后，当我交接文档时，仍有工作要做——但我对我们取得的成就感到满意。

自己看看吧：