Docs-as-code at Etsy
The question of documentation—not just formats and standards, but the tools and processes that can make documenting code a normal and repeatable part of development workflows—has been a live one in the software industry for a long time. The docs-as-code approach has emerged as a way of integrating documentation into development on the principle that the same sets of tools and procedures should be used for both. This might mean, for instance, versioning documentation the same way code is versioned, formatting it using plain-text markup like Markdown or reStructuredText, and employing automation tools to build and deploy documentation.
At Etsy, we've developed an internal tool called Docsbuilder to implement our own docs-as-code approach. It's our primary tool for maintaining and discovering software documentation at Etsy, and in this post we'll give you an overview of it.
What is Docs-as-code?
Docs-as-code aims to manage software documentation with the same level of rigor and attention typically brought to managing software source code. The goal of the methodology is to make the work of authoring, versioning, reviewing and publishing documentation smoother, more efficient, more repeatable and reliable.
The main principles of docs-as-code are:
- Documentation is a first-class citizen in the software development process
- As such, it should be versioned and stored in source control repositories such as Git
- Documentation should be written in plain-text formats like Markdown, to support versioning and collaboration
- Documentation should be reviewed and tested before being published
- The documentation workflow should be automated where possible to improve the reliability and user experience of publishing sites
Fundamentally, docs-as-code encourages an approach that balances documentation writing with coding. Developers who tag and release documentation the same way they do source code, with the same tools and procedures, will tend to be more organized and structured about handling their documentation. And the documentation itself becomes easier to audit for quality, and to update and maintain.
Docs-as-code at Etsy
Etsy's Docsbuilder tool is a collection of bin scripts, pipelines and processes that let developers create and maintain software documentation. Docsbuilder is Markdown-based; we use Docusaurus, a Facebook-created tool for generating project documentation websites, to convert Markdown files to HTML. Each project team at Etsy owns its own Docsbuilder repository, a mix of Markdown files, configurations and NPM dependencies, and we use a secure GitOps-based workflow to review and merge changes to these repositories.
To simplify the process of creating new sites, we developed a "docsbuilder-create" bin script. The script checks to make sure a supplied site name is valid and unique, then it bootstraps a Docusaurus site and installs all necessary Etsy-specific plugins.
Once the site is created, users can push documentation to their Git branch and open a pull request. To validate and test the PR, we use Google Cloud Build to clone a preconfigured Node.js container, which builds the entire documentation website and runs some integration tests to make sure the site is working properly.
When the tests are completed and the PR is approved, we merge the code into the main branch of the repository and another Cloud Build job then builds and deploys the site to production.
To make it easier for users within Etsy to find documentation, we developed a docs search engine that scans and indexes all Docsbuilder sites and all available pages. To simplify navigation, a React component displays a list of all important and frequently used sites on the homepage of our documentation hub.
In total, we currently host about 6.2k pages on 150 Docsbuilder project sites.
What’s Next
Discoverability and ease of use are important factors in making documentation more available, and that’s an area where we’re aiming to improve. Better links between doc sites and related topics will surface documentation better, as will improvements to the docs search engine. With the same idea in mind, we want to focus on creating more organized and navigable documentation pages. And there’s no reason not to make the content itself more engaging: we’re looking into adding more support for screenshots and other imagery, and integrating with React plugins to draw diagrams (e.g. flowcharts) and other visuals that can illustrate key concepts and ideas.
