Adopting Docs-as-Code at Pinte... Note

Adopting Docs-as-Code at Pinterest

Pinterest's internal developer surveys revealed that technical documentation is a top pain point, with issues boiling down to quality and discoverability. Traditional solutions, such as doc-a-thons and passionate appeals from senior leaders, have not produced lasting improvements. In 2021, Pinterest decided to try a new approach, exploring different strategies to enhance documentation tools and processes, with a focus on the "docs-as-code" strategy. This initiative, called PDocs, aimed to elevate the quality of technical documentation and transform the culture of documentation at Pinterest. The "docs-as-code" philosophy involves writing documentation using the same processes as code, including using markup languages, source control, code review tools, and static site generators. By adopting this strategy, Pinterest aimed to solve documentation problems, encouraging good documentation practices, quality control, and discoverability. PDocs, a custom-built static site generator, was developed to automatically colocate documentation projects from various file paths and repositories, generating a single centralized doc site. PDocs allows for a developer experience where engineers can drop a simple config and Markdown file in any repository, and have it show up in the centralized doc site once merged. The PDocs UI was designed to be project-centric, with features like favoriting, recently viewed, and a "published" or "draft" setting to maintain reader trust.
CdXz5zHNQW_I5dnAJn3pO.png