Overview
The article discusses Pinterest's adoption of the docs-as-code approach to improve technical documentation quality and discoverability. It details the development of PDocs, an internal documentation system that integrates documentation with source control and CI/CD processes.
What You'll Learn
1
How to implement a docs-as-code strategy to enhance documentation quality
2
Why using static site generators can streamline documentation processes
3
How to leverage internal tools like GitHub API for documentation management
4
When to utilize GenAI integrations to improve documentation accessibility
Prerequisites & Requirements
- Understanding of documentation practices and tools
- Familiarity with Markdown and CI/CD processes(optional)
Key Questions Answered
What is the docs-as-code approach and how is it implemented at Pinterest?
The docs-as-code approach involves writing documentation using the same tools and processes as code, such as Markdown and version control systems. At Pinterest, this is implemented through PDocs, which integrates documentation with source control, allowing for better collaboration, quality control, and discoverability.
What improvements have been observed in documentation quality at Pinterest?
Since the adoption of PDocs, Pinterest has seen a significant increase in documentation projects, with over 140 projects from 60+ GitHub repositories. Feedback from internal surveys indicates improved satisfaction with the documentation experience compared to previous wiki-style tools.
How does PDocs enhance the discoverability of documentation?
PDocs enhances discoverability by colocating documentation with the code it describes and indexing it into internal search providers. This allows engineers to find relevant documentation more easily and ensures that it is up-to-date alongside the code.
What role does GenAI play in PDocs?
GenAI is integrated into PDocs to enhance user experience by allowing users to ask AI questions directly while reading documentation. This integration helps to provide immediate assistance and improves the overall accessibility of information.
Key Statistics & Figures
Number of documentation projects
140+
PDocs has facilitated the creation of over 140 documentation projects from more than 60 GitHub repositories.
Number of teams using PDocs
80+
PDocs has been adopted by over 80 teams within Pinterest, indicating widespread acceptance and usage.
Technologies & Tools
Some links below are affiliate links. We may earn a commission if you make a purchase.
Documentation Tool
Pdocs
An internal documentation system developed to implement the docs-as-code strategy.
Markup Language
Markdown
Used for writing documentation in PDocs, making it compatible with LLMs.
Frontend Framework
Next.js
Used for static rendering and building the PDocs user interface.
API
Github API
Integrated for fetching metadata and facilitating documentation management.
Key Actionable Insights
1Adopting a docs-as-code strategy can significantly improve documentation quality and developer engagement.By integrating documentation with source control, teams can ensure that documentation evolves alongside the code, making it more relevant and up-to-date.
2Utilizing a centralized documentation tool like PDocs can streamline the documentation process across multiple projects.This approach reduces the overhead of setting up individual documentation sites and helps maintain consistency across documentation efforts.
3Implementing features that allow users to mark documentation as 'draft' can enhance user trust and prevent frustration.By hiding incomplete documents from search results, teams can ensure that users only encounter polished and reliable documentation.
Common Pitfalls
1
Failing to keep documentation updated alongside code changes can lead to outdated or inaccurate information.
This often occurs when documentation is treated as an afterthought rather than an integral part of the development process. To avoid this, teams should incorporate documentation updates into their pull request processes.
Related Concepts
Documentation Best Practices
CI/CD Integration For Documentation
Using Markdown For Technical Writing