"In this scenario, it doesn't make a lot of sense to target your API documentation exclusively at developers. It's definitely time to write it in a way that your non-technical stakeholders understand. So, how can you document your API capabilities?

Identifying capabilities is an exercise that begins with understanding the benefits your API offers to consumers. Benefits are the things that consumers obtain after they use your API, not what your API has to offer. You need to understand how consumers use your API and what their daily habits are. A good framework is studying your consumers' jobs-to-be-done (JTBD). Each JTBD represents something one or more consumers are trying to accomplish by using your API. After you group JTBDs by categories according to their similarity, you'll notice that clusters of benefits begin to emerge. If you then order those clusters by degree of criticality, you end up with a list of the most important benefits your API offers to potential consumers. I think you can already see where this is leading. With the list of benefits, you can get to a list of API capabilities by translating each one. While the benefit is what consumers achieve, the capability is what helps them get there. Let's look at an example to make things easier."

https://apichangelog.substack.com/p/documenting-your-api-around-its-capabilities

#API #APIs #APIDocumentation #TransactionEnrichment #TechnicalWriting #SoftwareDocumentation #SoftwareDevelopment