在Pinterest采用Docs-as-Code
[
[
Jacob Seiler | Software Engineer, Internal Tools PlatformJay Kim | Software Engineer, Internal Tools Platform
Jacob Seiler | 软件工程师，内部工具平台Jay Kim | 软件工程师，内部工具平台
Charlie Gu | Engineering Manager, Internal Tools Platform
Charlie Gu | 工程经理，内部工具平台
Technical documentation is the backbone of any successful engineering team, yet at Pinterest, it has consistently been a source of frustration. Despite using popular web-based wiki tools and experimenting with well-known alternative applications, our internal developer surveys reveal that documentation remains a top pain point. The issues boil down to two critical areas: quality and discoverability. Traditional solutions, such as doc-a-thon sprints or passionate appeals from senior leaders, have failed to produce lasting improvements. In 2021, we decided it was time to try something new.
技术文档是任何成功工程团队的支柱，但在 Pinterest，它始终是一个令人沮丧的来源。尽管使用流行的基于网络的维基工具并尝试了众所周知的替代应用程序，但我们的内部开发者调查显示，文档仍然是一个主要的痛点。问题归结为两个关键领域：质量和可发现性。传统解决方案，如文档马拉松冲刺或高级领导者的热情呼吁，未能产生持久的改善。在 2021 年，我们决定是时候尝试一些新东西了。
We began exploring different approaches to enhance our documentation tools and processes, with a particular focus on the docs-as-code strategy. This initiative aimed to not only elevate the quality of our technical documentation but also to transform the culture of documentation at Pinterest. The result was PDocs, our internal documentation system.
我们开始探索不同的方法来增强我们的文档工具和流程，特别关注文档即代码的策略。该倡议旨在不仅提升我们技术文档的质量，还要改变Pinterest的文档文化。最终结果是PDocs，我们的内部文档系统。
Docs-as-Code
文档即代码
Docs-as-code is the philosophy that you should be writing documentation using the same tools and processes you use for code. In practice, this means several things:
Docs-as-code 是一种理念，认为您应该使用与代码相同的工具和流程来编写文档。在实践中，这意味着几件事：
- Documentation is often written in a markup language such as Markdown.
- 文档通常使用标记语言编写，例如 ...