apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Roussel
0 likes164 views
The document discusses the state of API documentation, revealing that only 35% of API providers consider their documentation above average, while 57% regard it as a top priority. Key obstacles to effective API documentation include limited resources, time, and tooling support, with developers seeking ease of use, performance, and detailed documentation. The document also outlines characteristics of excellent API documentation and insights on how developers search for code, emphasizing the importance of providing clear examples and support.
apidays LIVE Singapore - Your API documentation powered by AI by Hervé Vu Roussel
- 1. @hvroussel @quod_ai Your API documentation powered by AI Herve Roussel Co-Founder at Quod AI
- 2. @hvroussel @quod_ai Only 35% of API providers feel that their API doc is above average. 57% say that API doc was top priority. Most API docs suck Source: State of API 2019 Report, SmartBear (2019)
- 3. @hvroussel @quod_ai Lack of resources, time, and tooling support are the biggest obstacles to implementing a successful API documentation process Obstacles for quality API Source: State of API 2019 Report, SmartBear (2019)
- 4. @hvroussel @quod_ai Most important needs for APIs 1. Ease of use 2. Performance 3. Detailed documentation What devs expect from APIs Source: State of API 2019 Report, SmartBear (2019)
- 5. @hvroussel @quod_ai 1. What’s good API doc? 2. How can we create good API doc? 3. How do we keep it easy? Agenda?
- 6. @hvroussel @quod_ai Excellent APIs docs Authentication guide Quickstart guide Endpoint definitions Code snippets Example responses Great API docs Interactive Readable and consumable Easy to find and search API status page A changelog Pricing What do devs want? What can I do? How can I do it? Source: Developer Portals with Great API Docs Pronovix (2018) Source: 5 Examples of Excellent API Documentation Nordic APIs (2019)
- 7. @hvroussel @quod_ai How do devs search for code? Find example code API consumer needs help Find example code Discover correct library for task Find example code Example to build off of Find example code How to do something Explore or read code Check implementation details Explore or read code Browsing Explore or read code Check best practices Explore or read code Name completion Find specific locations Trace through call graph Find specific locations Sharing Find specific locations Locations in source Find specific locations Trace code history Find specific locations Responsibility Determine impact Why is something failing? Determine impact Understanding dependencies Determine impact Side effects of a proposed change Source: How Developers Search for Code: A Case Study Google (2015)
- 8. @hvroussel @quod_ai Find example code API consumer needs help Find example code Discover correct library for task Find example code Example to build off of Find example code How to do something Explore or read code Check implementation details Explore or read code Browsing Explore or read code Check best practices Explore or read code Name completion Find specific locations Trace through call graph Find specific locations Sharing Find specific locations Locations in source Find specific locations Trace code history Find specific locations Responsibility Determine impact Why is something failing? Determine impact Understanding dependencies Determine impact Side effects of a proposed change How do devs search for code? What can I do? How can I do it? Source: How Developers Search for Code: A Case Study Google (2015)
- 9. @hvroussel @quod_ai API docs don’t have to be complex What can I do? How can I do it? Source: Stripe.com (2020)
- 10. @hvroussel @quod_ai 1. Introduction to APIs: Medium clone 2. Example API usage 3. Create awesome API docs with Quod AI 4. Run the code Demo time
- 11. @hvroussel @quod_ai What can I do? How can I do it?
- 12. @hvroussel @quod_ai Thank you! [email protected] Herve Roussel Co-Founder at Quod AI