Nobody reads the docs. In my experience about 15% of the people who work with APIs actually read the documentation, with another 35% of them scanning the documentation, and the rest never quite checking in with the documentation and resources being made available. With this in mind I am interested in exploring new options for ensuring teams producing APIs have the knowledge, awareness, and the guidance they need when they need it most.
I have long had a wealth of API knowledge available on API Evangelist, but the next round is designed to be what I am calling Just-in-Time API Guidance ™. This new approach to API governance focuses on guiding teams producing APIs on a single topic, providing 2-3 paragraphs and a video that help guide readers through the moment they are in. Just-in-Time API Guidance ™ is embedded in the strategy, policies, and rules used to govern API operations, and provide links for teams producing APIs to obtain the guidance they need–in the moment.
When a developer encounters a Spectral linting rule regarding HTTP status codes, there is also a link to the guidance for HTTP status codes–allowing the developer to click through, read more, watch a video, and understand why status codes matter. When a product manager encounters a spectral rule regarding summaries and descriptions for operations, the product manager can click through, read more, and watch a video to understand why these summaries and descriptions matter, and how they can impact documentation, and other customer facing resources.
This Just-in-Time API Guidance ™ is meant to be modular, snackable, and available in the tools and services where teams will encounter API policies and rules. Just-in-Time API Guidance ™ will help make up for the fact that teams don’t always read and understand API documentation, while also meeting them where they are, helping guide them throughout their API journey. Just-in-Time API Guidance ™ will evolve over time, adapt to each stage of the API lifecycle, and will always be shaped by the strategy, policies, and rules that the enterprise defines as part of their overall API governance.