November 2025 Summaries

Reorganizing a blog with over 200 posts covering topics like APIs, OpenAPI, and developer portals was undertaken to enhance content discovery and improve SEO. Previously, flat categories led to broad, hard-to-navigate groupings, which affected both user experience and search engine understanding. By implementing a hierarchical structure with categories and subcategories, like api-specifications:openapi or api-governance:linting-rulesets, the blog now offers clearer navigation paths and helps search engines better comprehend content relationships. This change allows readers to easily find related posts, fostering a deeper understanding of topics, and provides search engines with enhanced context for more accurate indexing. The reorganization, efficiently executed in just two days by a junior developer, is expected to yield long-term benefits in content discoverability and strategic content creation, with plans to maintain this structure for future posts.

API catalogs serve as crucial assets for modern engineering organizations, offering a comprehensive and automated system map that significantly enhances operational efficiency. As systems grow increasingly complex, with tens of thousands of interconnected entities such as APIs, services, and data assets, the absence of a centralized catalog leads to costly inefficiencies like prolonged search times, duplicate development, and extended incident resolutions. An automated API catalog mitigates these issues by providing accurate, real-time insights into dependencies, ownership, and lifecycle stages, thus reducing risk and enabling faster architectural decisions. It streamlines onboarding processes, facilitates cross-team collaboration, and ensures continuous governance without manual overhead. The catalog's automation fosters trust among engineers, encouraging its use and amplifying its value across the organization. In essence, an API catalog transforms chaotic systems into navigable maps, saving millions in engineering capacity and offering a competitive advantage by enabling organizations to evolve their architectures deliberately and efficiently.

Metrics should serve not only as tools for anomaly detection but also as instruments for continuous improvement. The article illustrates this through the author's personal experience with returning to competitive tennis, where reactive metrics like error rates and proactive metrics such as performance goals were both essential. Utilizing an app that provided detailed feedback on matches, the author was able to shift from random improvements to deliberate progress by setting specific goals and analyzing tactical errors through video review. This concept parallels business practices, where reactive metrics are vital for stability and detecting issues, while proactive metrics drive growth by setting clear objectives. By focusing on both types of metrics, teams can transform their approach from merely maintaining systems to actively striving for improvement, thus fostering a culture of growth and creativity.

November 2025 brings a host of updates to Redocly's product suite, including enhancements to AI assistants, support for OpenAPI 3.2.0, improved MCP integration, and new CLI validation features. These updates aim to improve search and SEO with the x-keywords extension and project title additions, enhance AI-powered documentation with new configuration options, and facilitate seamless MCP server integration through Markdoc tags and page actions for VSCode and Cursor. Redocly also introduces support for OpenAPI 3.2.0 with features like discriminator default mapping and offers more control over documentation through settings for mock servers, localization utilities, and customizable properties. The Redocly CLI sees enhancements with new validation rules for OpenAPI 3.2, configuration for mTLS certificates, and options for secrets masking. Additionally, Redocly is hiring software engineers to further develop its API documentation tools and shares a roadmap that includes experiments with AI assistants, runtime logs, a visual workflows builder, and performance improvements.

Many documentation teams struggle to measure the success of their efforts effectively, often relying on metrics like page views that don't directly reflect business value or developer engagement. To address this, organizations can focus on three key metrics aligned with developer experience: acquisition, adoption, and deflection. Acquisition involves attracting new developers by making documentation discoverable and accessible, adoption measures how well developers integrate APIs into their workflows, and deflection reduces support burdens by empowering developers with self-service tools. These metrics form a self-reinforcing value expansion loop, where improvements in one area can enhance the others, ultimately leading to sustainable growth and developer success. By choosing a primary metric based on organizational priorities and iterating on focused experiments, teams can create a shared dashboard to track these interconnected metrics, aligning their documentation strategy with business outcomes and developer needs.