Etsy Engineering Unveils “Docs-as-Code”: Blending Innovation and Craftsmanship
Introduction:
In the software industry, the question of documentation has always been a significant factor in development workflows. The docs-as-code approach has emerged as a solution to integrate documentation seamlessly into the development process. Etsy has developed their own internal tool called Docsbuilder, which follows the docs-as-code approach. This tool allows developers to create and maintain software documentation effectively. Documentation is treated as a first-class citizen in the software development process, with versioning and storage in source control repositories. Documentation is written in plain-text formats like Markdown, reviewed and tested before publishing, and automated tools improve the reliability and user experience. Etsy’s Docsbuilder tool uses Docusaurus to convert Markdown files to HTML, and a secure GitOps-based workflow is utilized for repository changes. Overall, the goal of the docs-as-code approach is to make software documentation more efficient, repeatable, and reliable.
Full Article: Etsy Engineering Unveils “Docs-as-Code”: Blending Innovation and Craftsmanship
## Etsy Implements a Docs-as-Code Approach with Docsbuilder Tool
The software industry has long debated the best approaches and tools for documenting code effectively. Etsy, an online marketplace, has embraced the docs-as-code approach and developed an internal tool called Docsbuilder to implement this methodology. Docs-as-code integrates documentation into the development process, using the same tools and procedures that are used for coding. This approach aims to make documenting code a normal and repeatable part of development workflows.
### The Docs-as-Code Methodology
Docs-as-code treats documentation as a first-class citizen in the software development process. It emphasizes the importance of versioning and storing documentation in source control repositories, such as Git. Markdown, a plain-text format, is favored for writing documentation as it supports versioning and collaboration. Before publishing, documentation should go through a review and testing process. Automation tools are also recommended to improve the reliability and user experience of publishing sites.
### Benefits of the Docs-as-Code Approach
By treating documentation as code, developers can be more organized and structured in handling their documentation. Developers who tag and release documentation in the same way they do source code tend to have a smoother workflow. It also becomes easier to audit and update the documentation. The docs-as-code approach encourages a balanced approach to documentation, ensuring that code and documentation go hand in hand.
### Etsy’s Docsbuilder Tool
Etsy has developed Docsbuilder, an internal tool that allows developers to create and maintain software documentation. Docsbuilder is based on Markdown and utilizes Docusaurus, a tool developed by Facebook, to convert Markdown files into HTML for generating project documentation websites. Each project team at Etsy has its own Docsbuilder repository, consisting of Markdown files, configurations, and NPM dependencies.
To simplify the process of creating new sites, Etsy created a “docsbuilder-create” bin script. This script checks the validity and uniqueness of the site name and then sets up a Docusaurus site with all the necessary Etsy-specific plugins. Once the site is created, users can push documentation to their Git branch and open a pull request for review.
To validate and test the pull request, Google Cloud Build is used to clone a preconfigured Node.js container. This container builds the entire documentation website and runs integration tests to ensure the site functions properly. Once the tests are completed and the pull request is approved, the code is merged into the main branch of the repository. Another Cloud Build job then builds and deploys the site to production.
### Enhancing Discoverability and Ease of Use
Etsy aims to improve the discoverability and ease of use of its documentation. To help users find documentation more easily within Etsy, a docs search engine that scans and indexes all Docsbuilder sites and pages has been developed. Additionally, a React component displays a list of important and frequently used sites on the homepage of Etsy’s documentation hub, simplifying navigation.
Looking ahead, Etsy plans to focus on improving the links between doc sites and related topics to enhance the visibility of documentation. The company also intends to make documentation pages more organized and navigable. In terms of content, Etsy is exploring ways to make it more engaging by adding support for screenshots, imagery, and integrating React plugins for diagrams and visuals that can illustrate key concepts and ideas.
In conclusion, Etsy’s implementation of the docs-as-code approach through the Docsbuilder tool demonstrates their commitment to making documentation management as rigorous and efficient as software development. By integrating documentation into the development process and utilizing automation tools, Etsy aims to enhance the quality, accessibility, and usability of their documentation for both developers and users.
Summary: Etsy Engineering Unveils “Docs-as-Code”: Blending Innovation and Craftsmanship
Documentation in software development has always been an important topic, and the docs-as-code approach has emerged as a solution. At Etsy, they have developed a tool called Docsbuilder that implements the docs-as-code approach. This tool helps manage software documentation by integrating it into development workflows, versioning it like code, and using plain-text formats like Markdown. Docs-as-code encourages a balanced approach between documentation and coding, making developers more organized and structured in handling their documentation. Etsy’s Docsbuilder tool is a collection of scripts and processes that enable developers to create and maintain software documentation. It utilizes Docusaurus to convert Markdown files to HTML and follows a GitOps-based workflow for reviewing and merging changes. To improve discoverability, they have developed a docs search engine that scans and indexes all Docsbuilder sites. Overall, Etsy aims to make documentation more available, organized, and engaging by enhancing discoverability, navigation, and content presentation.
Frequently Asked Questions:
Q1: What is machine learning?
A1: Machine learning is a field of artificial intelligence that focuses on developing computer algorithms capable of learning from and making predictions or decisions based on data. It involves training a model on a set of data to recognize patterns and make accurate predictions or decisions without being explicitly programmed.
Q2: What are the different types of machine learning algorithms?
A2: There are three main types of machine learning algorithms: supervised learning, unsupervised learning, and reinforcement learning. Supervised learning uses labeled data to train the model, while unsupervised learning identifies patterns in unlabeled data. Reinforcement learning involves an agent learning through a trial-and-error process to maximize rewards in a given environment.
Q3: What are some popular applications of machine learning?
A3: Machine learning finds applications in various domains, including image and speech recognition, natural language processing, recommendation systems, fraud detection, autonomous vehicles, and healthcare. It enables advances in personalization, automation, and decision-making by analyzing vast amounts of data and providing valuable insights.
Q4: What are the key steps involved in a machine learning project?
A4: A typical machine learning project involves several key steps. These include defining the problem and collecting relevant data, preprocessing and preparing the data, selecting an appropriate algorithm, training the model on the data, evaluating the model’s performance, fine-tuning and optimizing the model, and finally deploying it for real-world use.
Q5: What are the challenges associated with machine learning?
A5: Machine learning faces several challenges, such as obtaining and preparing high-quality data, addressing biases and ethical considerations, selecting the right algorithms for a given problem, avoiding overfitting or underfitting of the model, and scaling the solution to handle large datasets and real-time applications. Furthermore, interpretability, security, and privacy concerns also need to be carefully addressed in machine learning systems.
