Docs-as-code at Etsy

Docs-as-code integrates documentation into development using the same tools and procedures as code. It emphasizes versioning, plain-text markup, and automation for improved documentation management. Etsy's Docsbuilder tool employs Markdown, Docusaurus, and GitOps workflows for documentation creation and maintenance. Docsbuilder automates site creation, validation, and deployment with Google Cloud Build and integration tests. Docsbuilder enables discoverability with a search engine and a navigation component for frequently used sites. Etsy currently hosts over 6.2k pages on 150 Docsbuilder sites. The goal of docs-as-code is to enhance documentation quality, efficiency, and reliability. Key principles include treating documentation as a first-class citizen, versioning in Git, using plain-text formats, and automating workflows. Docs-as-code encourages developers to approach documentation with the same rigor as coding. Etsy plans to improve discoverability, navigation, and content engagement within Docsbuilder. Docs-as-code fosters a balanced approach between documentation and coding, leading to organized and maintainable documentation.