July 2024 Summaries

Redocly has been actively working on integrating and expanding the Arazzo Specification, which they consider vital for sharing domain knowledge and documenting data dependencies in API operations. After Lorna joined the company and introduced the SIG-Workflows group, Redocly realized they had independently developed a similar tool, initially named Spot, now renamed Respect, for E2E API contract testing. This led to their significant contributions to the officially released Arazzo Specification. Their roadmap includes developing tools like a visual editor and a linter for Arazzo, with some tools already completed and others in progress. Redocly also launched a learning center for Arazzo, encouraging community involvement and offering opportunities to join their team as they continue to develop and refine their tools and processes.

The Arazzo specification, which builds on the OpenAPI standards, enhances API workflows by allowing the description of complex sequences of API requests, defining success criteria, and using response data from one request as input for another. This capability enables the documentation of multi-request tasks, client generation for integrated API functions, and simplified testing of API workflows. Arazzo supports cross-API workflows within an organization and with third-party APIs, offering broad application potential. Redocly, an early adopter of Arazzo, transitioned from custom internal API testing syntax to Arazzo, contributing to its development despite facing challenges due to its evolving nature. The Redocly CLI tool supports Arazzo linting, facilitating validation and error-checking for Arazzo descriptions as part of the API lifecycle, and provides resources for users to implement and explore the new standard.

Documentation migration presents an opportunity for growth and improvement while also posing challenges that can be managed with a strategic approach. A successful migration involves a clear timeline, engaging stakeholders early, identifying allies, enabling contributors, and developing an effective communication process. Key steps include using content inventories, planning information architecture, automating content conversion, tracking migration status, and planning a redirect strategy to maintain user experience. Quality assurance and a deployment plan are essential, along with a robust feedback and rollback strategy to address potential issues and ensure a smooth transition. The process, if well-managed, can unify and energize both writers and readers, ultimately enhancing the user experience and organizational efficiency.

Docs-as-code is an approach that integrates software development tools and processes, such as source control, into documentation projects to enhance productivity and maintainability. Key to this approach is the use of branching strategies within git, which facilitates separate lines of work and collaborative efforts. The text outlines three primary branching strategies: trunk-based development, where changes are directly committed to the main branch; GitHub flow, which involves creating branches for each change and using pull requests for merging; and versioned branches, used for maintaining multiple versions of documentation concurrently. Each strategy has its advantages, such as simplicity in trunk-based development, thorough review processes in GitHub flow, and effective management of multiple versions in versioned branching. The choice of strategy depends on the project's specific needs, team size, and skill levels, with the flexibility to adapt and evolve these workflows as the project progresses. Various resources, including learning materials on git and tools like mermaid.js for visualizing workflows, support these docs-as-code practices.