November 2022 Summaries

API documentation serves as the user interface for APIs, which lack a front end, and is crucial for developers to understand and implement APIs into their code. There are two main types of API documentation: reference docs, which describe an API's schema and format, and contextual docs, which provide tutorials, authentication methods, error codes, rate limits, and pricing. The docs-as-code approach, advocated by the global technical writers' community Write the Docs, promotes treating documentation with the same tools and workflows as code, fostering collaboration between writers and developers. This method leverages the OpenAPI Specification (OAS) to define APIs in a standardized format, often using YAML or JSON, which can be transformed into interactive documentation with tools like Redocly. Redocly's tools automate the process of organizing, validating, and publishing API docs, embodying the docs-as-code philosophy to streamline documentation and enhance collaboration.

Jody, a technical writer at Redocly in Auckland, New Zealand, has launched a series aimed at helping newcomers to open source, command lines, GitHub, and docs-as-code become familiar with Redocly's products. As someone who initially struggled with these concepts, Jody shares their learning journey to assist others in navigating and utilizing Redocly's open-source tools effectively. The series is designed for tech writers who may feel intimidated by unfamiliar terms or tasked with automating their company's API documentation without knowing where to start. It introduces core concepts necessary for maximizing the benefits of Redocly's free tools, such as the Redocly CLI and Redoc, which help organize, validate, and publish API documentation. Jody emphasizes the importance of understanding open-source software, defined as software with source code that anyone can inspect, modify, and enhance, and encourages readers to engage with the open-source community. The series begins with an exploration of the concept of open source and its significance, setting the stage for deeper dives into Redocly's specific tools in future installments.