Over the past few years, Pinterest engineers have been working to adopt Docs-as-Code across the organization. By using the same tools and processes for both code and documentation, they’ve improved overall documentation quality and team satisfaction. The shift also helped transform Pinterest’s documentation culture, fostering collaboration, improving quality control, discoverability, and more.
Using Docs-as-Code means treating documentation artifacts like code, making it more natural for engineers to write and maintain documentation. This involves using a markup language like Markdown, Asciidoc, or others; managing documentation with source control tools; enforcing CI/CD processes to validate and publish it; and automatically generating the final output, typically as an HTML site.
In Pinterest’s case, adopting a docs-as-code strategy involved standardizing on Markdown and Git, and integrating documentation into their review and deployment pipelines just like code. They also developed dedicated tooling for documentation management, including support for metadata, templates, and search.
We felt adopting a docs-as-code strategy would help solve our documentation problems. In summary, we can create a system that encourages good documentation practices just by using it.
Specifically, this shift addressed several issues with the processes and tools they used previously, including the difficulty of proposing changes and iterating on feedback, the challenge of ensuring all relevant stakeholders could review updates, and the low discoverability caused by keeping code and documentation in separate locations. Another nuisance was that using WYSIWYG editors for documentation tended to mix style and content, which should remain separate concerns.
In addition, adopting a docs-as-code strategy also brought broader benefits, such as increasing the likelihood of having up-to-date documentation and enabling earlier detection of design or usability issues.
By evolving the docs alongside code, you get an early sneak peak of developer experience by reading the docs. Often, usability gaps in the APIs you are trying to ship only reveal themselves once you realize how awkward the documentation is.
As mentioned, Pinterest developed an internal tool, Pinterest Docs (Pdocs), to streamline their processes and allow documentation to be hosted across multiple repositories:
To minimize the fixed cost of setting up a documentation project, we wanted a static site generator that could automatically colocate documentation projects from various file paths and repositories and generate a single centralized doc site.
Specifically, this approach avoided the overhead of setting up a new documentation project for each repository, including configuring tools like Docusaurus and MkDocs, creating boilerplate, installing dependencies, and establishing a CI/CD pipeline.
To this end, PDocs crawls all repositories for pdocs.yaml files that list which Markdown files to parse into HTML. A CLI tool simplifies usage by enabling project creation with basic configuration and templates, and by running a live-reload server for previewing documentation during development.
Pinterest considers the docs-as-code adoption a success, with internal surveys and feedback indicating that "writing and browsing documents in PDocs is a much better experience than using our existing wiki-style tools".
A key factor was the creation of a "Wiki to PDocs converter", which led to a 20% increase in documentation projects in just two months, surpassing 140. Encouraged by this, Pinterest plans to keep improving the tool by streamlining the writing experience and enhancing collaboration.
Beyond Pinterest, docs-as-code is used at many large organizations, including AWS, the UK Government, and GitHub. If you’re looking to adopt this strategy in your team or organization, the Write the Docs site is a great place to start.