User Brainpower vs. AI Blind Spots in API Docs

Anyone who writes API documentation—engineers, technical writers—can use AI to improve writing. But even AI has blind spots.

This talk by Rebecca McIntosh, Senior Technical Communicator at nCino (AIFinTech100 2025), is about making API documentation easier to understand so that users can use their brainpower on being creative with your APIs instead of wasting energy trying to understand them. It explains how superficial AI usage can worsen the API user experience and how to use it strategically to set up your users for success.

Transcript

1. rebecca-mc “Platforms, Products, and People: The Power of APIs in the Age of AI” API Days conference theme Application Programming Interface Artificial Intelligence Engineers Users of API docs How do we enable engineers who use documentation? What do we know about cognition and how we solve problems? How does it change when we use AI?
2. rebecca-mc User Brainpower vs. AI Blind Spots in API Docs Rebecca McIntosh rebecca-mc 29th October 2025 for API Days
3. rebecca-mc Technical communication professional rebecca-mc Rebecca McIntosh Senior Technical Communicator Fintech: Financial institution software Fintech: Point of Sale software Technical Writer 2016-2021 (5 years) 2021-current (4+ years)
4. rebecca-mc
5. rebecca-mc User Brainpower vs. AI Blind Spots in API Docs User brainpower AI blind spots API doc examples Strategy
6. rebecca-mc User Brainpower The finite cognitive resources that users (engineers) have available for problem-solving, learning, and creative work.
7. rebecca-mc Cognitive Load Theory Intrinsic load Actual problem to solve Extraneous load Irrelevant, poorly presented information Germane load Building understanding, mental models According to John Sweller
8. rebecca-mc ▭ × ▭ − ▭ = 21 III 2 17 XVI XI 3 IV VIII How many ways can you solve this problem?
9. rebecca-mc ▭ × ▭ − ▭ = 21 III 2 17 XVI XI 3 IV VIII How many ways can you solve this problem? 3 16 11 8 Extraneous load III = ? XI = ? Intrinsic load 4
10. rebecca-mc How users engage with API docs User API Doc
11. rebecca-mc User API Doc User API Doc AI
12. rebecca-mc User API Doc AI
13. rebecca-mc User API Doc AI
14. rebecca-mc Intrinsic load Extraneous load Germane load User API Doc User API Doc AI User API Doc AI
15. rebecca-mc AI Blind Spots We risk burdening users with an extraneous cognitive load that consumes their brainpower
16. rebecca-mc
17. rebecca-mc ence: AI Fluency course from Anthropic
18. rebecca-mc ence: AI Fluency course from Anthropic AI Limitations • Incorrect information • Hallucination • Context window • Non-deterministic output
19. rebecca-mc ence: AI Fluency course from Anthropic AI Limitations • Incorrect information • Hallucination • Context window • Non-deterministic output
20. rebecca-mc AI Limitations • Incorrect information • Hallucination • Context window • Non-deterministic output • Use cognitive resources on troubleshooting and rework • Unable to complete tasks • Unable to build a mental model Risks for users “[C]reative variability can be great for brainstorming […] but requires awareness when consistency or accuracy are critical” —Anthropic Academy AI Fluency: Framework & Foundations course Reference: AI Fluency course from Anthropic
21. rebecca-mc POST /v1/shipments Creates one or multiple shipment records in the system. POST /v1/packages Add new package to database. Supports bulk operations. POST /v1/deliveries Endpoint for delivery creation. Example API endpoint descriptions
22. rebecca-mc
23. rebecca-mc
24. rebecca-mc Onus is on the user
25. rebecca-mc How users might engage with API docs User API Doc AI ?
26. rebecca-mc Strategy Create standards for your documentation.
27. rebecca-mc API API API API API API “improve writing” The different wording suggests there might be a meaningful distinction “create an API doc” + variability + variability Using AI without standards
28. rebecca-mc Standardisation Create standards Strategic decisions ability has a distinct meaning. Formatting Research Discussion Limiting variability Communicative commitment Any different wording exists only when there is a meaningful distinction
29. rebecca-mc Standardisation Create standards Standardise API documentation Revise and review ely engage with decision-makers to share a vision.
30. rebecca-mc API API API API API API + standard + standard + standard Using AI with standards
31. rebecca-mc API Doc Examples How to standardise information
32. rebecca-mc
33. rebecca-mc
34. rebecca-mc
35. rebecca-mc Rewrite each API description to follow this structure: [Action verb] + [specific task] + [location if needed]. Start with an imperative verb, focus on what developers can accomplish, use active voice, and keep each description to one clear sentence under 15 words. Context: *Location is needed only for shipping APIs Action-oriented Concise Tutorials
36. rebecca-mc
37. rebecca-mc POST /v1/shipments Creates one or multiple shipment records in the system with comprehensive tracking capabilities. Unstandardised endpoint descriptions POST /v1/packages Add new package to database. Supports bulk operations. POST /v1/deliveries Endpoint for delivery creation. This API allows users to establish delivery records with various delivery types and flexible reporting options in the logistics platform.
38. rebecca-mc
39. rebecca-mc
40. rebecca-mc POST /v1/shipments Creates one or multiple shipment records in the system with comprehensive tracking capabilities. POST /v1/packages Add new package to database. Supports bulk operations. POST /v1/deliveries Endpoint for delivery creation. This API allows users to establish delivery records with various delivery types and flexible reporting options in the logistics platform. POST /v1/shipments Create new shipment records. POST /v1/packages Create new package records. POST /v1/deliveries Create new delivery records. Unstandardised Standardised
41. rebecca-mc GET /v1/shipments/{id} Retrieve shipment details by ID. Standardised APIs among many PUT /v1/deliveries/{id}/status Update delivery status. POST /v1/shipments Create new shipment records. POST /v1/packages Create new package records. POST /v1/deliveries Create new delivery records. GET /v1/packages/{id} Retrieve package details by ID. GET /v1/deliveries/{id} Retrieve delivery details by ID. PUT /v1/package/{id}/status Update package status. PUT /v1/shipments/{id}/status Update shipment status.
42. rebecca-mc GET /v1/orders customer (string): The ID of the customer to retrieve order records for. Unstandardised parameter descriptions POST /v1/payments customer (string): Customer who will be charged for this payment. GET /v1/shipments/{id}/history customer (string): Filter by customer - use this if you want to see only events visible to a specific customer account.
43. rebecca-mc GET /v1/orders customer (string): The ID of the customer to retrieve order records for. POST /v1/payments customer (string): Customer who will be charged for this payment. GET /v1/shipments/{id}/history customer (string): Filter by customer - use this if you want to see only events visible to a specific customer account. GET /v1/orders customer (string): Customer ID POST /v1/payments customer (string): Customer ID GET /v1/shipments/{id}/history customer (string): Customer ID GET /v1/orders customer (string): ID of the customer whose order to retrieve. POST /v1/payments customer (string): ID of the customer to charge for this payment. GET /v1/shipments/{id}/history customer (string): ID of the customer to filter events for. Unstandardised Standard A Standard B
44. rebecca-mc The power of APIs in the age of AI can only be harnessed if we consider our users’ cognitive load and AI’s blind spots. People
45. rebecca-mc References The power of APIs in the age of AI can only be harnessed if we consider our users’ cognitive load and AI’s blind spots. People Anthropic. (2025). Claude [Large language model]. Accessed September 2025. https://claude.ai/ Anthropic Academy. (2025). AI Fluency: Framework & Foundations. https://anthropic.skilljar.com/ai-fluency-framework-foundations Paas, F., Renkl, A., & Sweller, J. (2003). Cognitive load theory and instructional design: Recent developments. Educational Psychologist, 38(1), 1–4. https://www.uky.edu/~gmswan3/544/Cognitive_Load_%26_ID.pdf Sweller, J. (1994). Cognitive load theory, learning difficulty, and instructional design. Learning and Instruction, 4(4), 295–312. https://doi.org/10.1016/0959-4752(94)90003-5
46. rebecca-mc rebecca-mc Add me on LinkedIn!