文档即代码如何帮助 Pinterest 提高文档质量

在过去的几年里，Pinterest 的工程师一直致力于在整个组织内采用文档即代码（Docs-as-Code）的做法。通过使用相同的工具和流程来处理代码和文档，他们提高了整体文档质量和团队满意度。这种转变还帮助转变了 Pinterest 的文档文化，促进了协作，提高了质量控制、可发现性等。

使用文档即代码意味着像对待代码一样对待文档构件，使工程师更自然地编写和维护文档。这包括使用像 Markdown、Asciidoc 或其他标记语言；使用源代码控制工具管理文档；执行 CI/CD 流程来验证和发布文档；并自动生成最终输出，通常是 HTML 网站。

在 Pinterest 的案例下，采用文档即代码的策略涉及标准化 Markdown 和 Git，并将文档像代码一样集成到他们的审查和部署流程中。他们还开发了用于文档管理的专用工具，包括对元数据、模板和搜索的支持。

我们认为采用文档即代码策略将有助于解决我们的文档问题。总之，我们可以通过使用它来创建一个鼓励良好文档实践的系统。

具体来说，这种转变解决了他们之前使用的流程和工具中的几个问题，包括提出更改和迭代反馈的困难，确保所有相关利益方都能审查更新的挑战，以及由于将代码和文档保存在不同位置而导致的低可发现性。另一个麻烦点是，使用所见即所得（WYSIWYG）编辑器进行文档编写往往会混合样式和内容，这应该是分开关注的问题。

此外，采用文档即代码策略还带来了更广泛的好处，例如增加了拥有最新文档的可能性，并能够更早地发现设计或可用性问题。

通过在编写代码的同时编写文档，你可以通过阅读文档提前了解开发人员的经验。通常情况下，你试图发布的 API 的可用性差距只有在你意识到文档有多尴尬时才会显现出来。

如前所述，Pinterest 开发了一个内部工具，Pinterest Docs（Pdocs），以简化他们的流程，并允许文档托管在多个存储库中：

为了最小化设置文档项目的固定成本，我们希望有一个静态站点生成器，它可以自动地从各种文件路径和存储库中配置文档项目，并生成单个集中的文档站点。

具体来说，这种方法避免了为每个仓库设置新文档项目的开销，包括配置像Docusaurus和MkDocs这样的工具，创建样板文件，安装依赖项，以及建立 CI/CD 管道。

为此，PDocs 会爬取所有仓库中的 pdocs.yaml 文件，这些文件列出了哪些 Markdown 文件需要解析成 HTML。CLI 工具通过启用基本配置和模板创建项目，以及在开发期间运行实时重载服务器以预览文档，从而简化了使用。

Pinterest 认为文档即代码的采用是成功的，内部调查和反馈表明，“在 PDocs 中编写和浏览文档比使用我们现有的维基风格的工具要好得多”。

一个关键因素是创建了一个“维基到 PDocs 转换器”，这在短短两个月内使文档项目增加了 20%，超过了 140 个。受此鼓舞，Pinterest 计划通过简化编写体验和增强协作来继续改进这一工具。

除了 Pinterest，许多大型组织也在使用文档即代码，包括 AWS、英国政府和GitHub。如果你希望在你的团队或组织中采用这种策略，那么Write the Docs网站是一个很好的起点。

原文链接：

https://www.infoq.com/news/2025/06/docs-as-code-at-pinterest/