The angle from which to look at the business value of API documentation is the “platform.” When building it, APIs are the core ingredient and the area where different teams interact. Poor documentation affects cross-team collaboration, impacting integration times and incident response. It hinders efforts to achieve predictable, fast delivery and efficient operations. This ultimately affects the teams' ability to reach those business goals and costs $$$. This issue will likely surface in organization-wide surveys.

API documentation can be so much more than API documentation. [It] can be the thread connecting all the stages of the API consumer lifecycle. https://notes.brunopedro.com/2024/06/27/20240627230846/

Challenges in API usability, as highlighted by Scaffidi [18] and [16], include inadequate documentation, insufficient orthogonality, and mismatches between API abstractions and application requirements. https://dl.acm.org/doi/10.1145/3613905.3650803

Given the right documentation, self-service API integration should come naturally, right? What is the proper documentation though and who defines that? Working with teams to reduce the problem to a “set of questions” that the docs must answer, can help you move towards self-service.